Official documentation checked October 14, 2026.
The public Perplexity API documentation does not establish the Webhooks dashboard, event names or signature header described by older tutorials. Do not expose a server endpoint expecting Perplexity to send an undocumented signed callback.
The supported route documented for long Agent API jobs is background execution with response-ID retrieval. Your application can then send its own completion notification. That is an application design, separate from a provider-delivered webhook.
Check the Provider Contract Before Opening an Endpoint
The current official API documentation index lists Agent response creation, retrieval, cancellation and background mode, but no verified general webhook registration contract. This absence limits what this guide can instruct; it is not a claim that no future or separately contracted feature can exist.
Do not assume an X-Perplexity-Signature header, search.completed event, five-second acknowledgement rule, three retries or a Webhooks menu. If a vendor offers you a different contract, verify its official documentation, authentication, replay handling and data scope before implementing it.
Use the Documented Background Response Workflow
Perplexity’s Background Mode guide documents background=true when creating an Agent response at POST /v1/agent. Keep the returned response ID and retrieve that same run rather than submitting the paid work again after a timeout.
Retrieve status with GET /v1/agent/{id}. Distinguish running states from every documented terminal outcome. Only a completed result should become a success notification; failure, cancellation and incomplete output need separate handling. Do not equate an accepted request with finished work.
The retrieval reference says responses created with store: false return 404 on retrieval. Confirm supported storage and retention settings for the workflow; never interpret every 404 as permission to recreate the run or expose its identifier publicly.
Design Your Application’s Notification Safely
As an application pattern, keep a private job record linking the provider response to the authorized user and your internal job. A worker can retrieve outstanding jobs with a bounded polling schedule and mark each terminal outcome once. Choose limits appropriate to your workload rather than copying an undocumented universal frequency or TTL.
Keep the API credential on the server in approved secret storage. Protect result retrieval with your application’s user authorization; knowing a response ID must not grant access to another user’s work. Store only the diagnostics you need and avoid logging keys or private result bodies.
If your application posts to a downstream callback, authenticate that callback under your own documented contract, restrict its recipients and make delivery idempotent. Prevent arbitrary user-supplied URLs from making your worker access internal services. Do not label that custom callback a verified Perplexity webhook.
Troubleshoot the Existing Run Without Duplicate Spending
On a connection drop, inspect the saved ID and current state. The background guide also documents streaming reconnection with a sequence cursor and a limited reconnect window; once the window expires, use a plain retrieval for the snapshot. Do not guarantee indefinite reconnection.
Perplexity’s SDK error-handling guide provides the provider-specific failure context. Coordinate your worker’s retry policy with the SDK rather than stacking unlimited retries. Record endpoint, response ID, time and redacted error details for official API support.
No API call or public callback server is created by this article. Before deploying a paid job workflow, review its documented API security and operational practices and verify your own authorization, storage, retry and notification behavior in an approved test environment.
Glad it helped. Take a short break with a game:
Sorry about that. Search for the exact error message, or look for a tool that checks your device: