How to Set up Perplexity API Webhook Notifications

Perplexity API users often need to receive real-time updates when a search or analysis completes, rather than polling the API manually. Webhook notifications let Perplexity push results directly to your server when a task finishes, saving bandwidth and reducing latency. This article explains how to configure a webhook endpoint, register it with Perplexity, and handle incoming notifications in your backend. You will learn the exact steps to enable webhook delivery for your API key.

How Perplexity Webhook Notifications Work

A webhook is an HTTP callback that Perplexity sends to your server when a specific event occurs. Instead of repeatedly calling the API to check if a search is done, Perplexity pushes the result to your endpoint as soon as it completes. This reduces API usage and gives you instant data.

To use webhooks, you need a publicly accessible HTTPS endpoint on your server. Perplexity sends a POST request to that endpoint with a JSON body. The payload includes the task ID, the status (completed, failed, or cancelled), and the search results or error message. You must respond with a 200 OK status within 5 seconds to acknowledge receipt. If Perplexity does not receive a 200, it retries up to three times with increasing delays.

Each webhook request includes an HMAC-SHA256 signature in the X-Perplexity-Signature header. You must verify this signature using your secret webhook token to ensure the request genuinely came from Perplexity and was not modified in transit. Without verification, an attacker could send fake results to your server.

Steps to Register a Webhook Endpoint in Perplexity

1. Log into the Perplexity Dashboard
   Go to perplexity.ai/settings/api. Sign in with your account credentials. You must have an active API subscription to access webhook settings.
2. Open the Webhooks Configuration Page
   In the left sidebar, click Webhooks. This page lists all registered webhook endpoints for your account.
3. Click Add Endpoint
   Click the blue Add Endpoint button at the top right. A form opens with fields for the endpoint URL, secret token, and event filters.
4. Enter Your Endpoint URL
   Type the full HTTPS URL of your server endpoint that will receive webhooks. For example: https://yourdomain.com/perplexity-webhook. The URL must use HTTPS with a valid SSL certificate. Perplexity will not send requests to HTTP or self-signed certificate URLs.
5. Generate and Save a Secret Token
   In the Secret Token field, type a random string of at least 32 characters. You can generate one using a password manager or a command like openssl rand -hex 32. Copy this token and store it securely on your server. You will use it to verify incoming webhook signatures.
6. Select the Events to Receive
   Check the boxes for the events you want to be notified about. The available events are:
   – search.completed: A search request finished successfully
   – search.failed: A search request returned an error
   – search.cancelled: A search request was cancelled by the user or system
   Select at least one event. For most use cases, check all three to stay informed of every state change.
7. Click Save Endpoint
   Click the Save button at the bottom of the form. Perplexity sends a test notification to your endpoint to verify connectivity. Your server must respond with a 200 OK within 5 seconds. If the test fails, the endpoint is not saved, and you see an error message. Check your server logs and endpoint code, then retry.

How to Handle Incoming Webhook Requests on Your Server

Once your endpoint is registered, you must write server-side code to receive, verify, and process the incoming POST requests. Below is a generic workflow that works in any programming language. The example uses Node.js with Express, but the logic applies to Python, Ruby, PHP, or any other language.

Verify the HMAC-SHA256 Signature

Every webhook request includes a header named X-Perplexity-Signature. The value is a hexadecimal string. To verify it, compute an HMAC-SHA256 hash of the raw request body using your secret token as the key. Compare the computed hash to the signature header. If they do not match, reject the request with a 401 Unauthorized status and do not process the payload.

Parse the JSON Payload

The request body is a JSON object with the following structure:

{
  "event": "search.completed",
  "task_id": "abc123-def456",
  "status": "completed",
  "result": {
    "query": "latest AI research papers",
    "answer": "...",
    "sources": ["..."],
    "created_at": "2025-03-15T10:30:00Z"
  },
  "error": null
}

The event field tells you which event triggered the notification. The task_id matches the ID you received when you submitted the search request. Use this ID to correlate the webhook with your internal records. The result object contains the full search results if the event is search.completed. For search.failed, the error field contains a description of the failure.

Respond With a 200 OK

After verifying the signature and parsing the payload, send a 200 OK response with an empty body. Perplexity expects this response within 5 seconds. If you need to perform heavy processing, do it asynchronously after sending the 200. For example, push the payload to a message queue or a background job processor.

Sample Node.js Handler Code

const express = require('express');
const crypto = require('crypto');

const app = express();
const SECRET_TOKEN = 'your-secret-token-here';

app.post('/perplexity-webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-perplexity-signature'];
  const payload = req.body;
  const computed = crypto.createHmac('sha256', SECRET_TOKEN)
                         .update(payload)
                         .digest('hex');
  if (signature !== computed) {
    return res.status(401).send('Invalid signature');
  }
  const data = JSON.parse(payload);
  console.log('Webhook received:', data.event, data.task_id);
  // Process the result asynchronously
  res.status(200).send();
});

app.listen(3000, () => console.log('Webhook listener on port 3000'));

Common Webhook Setup Mistakes and How to Avoid Them

Webhook Test Fails With a 5xx Error

The most common cause is that your server endpoint is not reachable from the internet. Perplexity must be able to resolve your domain and establish a TLS connection. Check that your server is running, your firewall allows inbound traffic on port 443, and your SSL certificate is valid and not self-signed. Use a tool like curl to test the endpoint manually: curl -X POST https://yourdomain.com/perplexity-webhook -d '{"test": true}' -H "Content-Type: application/json".

Webhook Payload Is Not Processed

If you see the webhook arriving in your server logs but the data is not saved or acted upon, the issue is likely in your processing logic. Ensure you are parsing the JSON body correctly. Many frameworks parse the body automatically, but you must use the raw body for signature verification. If you parse the body before verifying the signature, the hash will not match. In Express, use express.raw() as shown above, then parse manually after verification.

Multiple Webhooks for the Same Task

Perplexity may send duplicate webhooks if it does not receive a 200 OK within 5 seconds. If your server responds slowly, the retry mechanism sends the same payload again. To handle duplicates, make your processing idempotent. Check if you have already processed a task_id before saving the result. Store processed task IDs in a database or cache with a TTL of at least one hour.

Item	Without Webhooks	With Webhooks
Polling method	Client calls GET /v1/search/status every few seconds	Perplexity pushes POST to your endpoint when task finishes
API call volume	High: many polling requests per task	Low: one push per event, no polling
Result latency	Up to polling interval (e.g., 5 seconds delay)	Near real-time (sub-second)
Server complexity	Simple: just a GET endpoint	Moderate: must verify HMAC and handle retries
Cost	Higher API usage, more bandwidth	Lower API usage, less bandwidth

You can now set up Perplexity API webhook notifications to receive search results as soon as they complete. Start by registering your HTTPS endpoint in the Perplexity dashboard and generating a secret token. Then implement signature verification and idempotent processing on your server. For high-traffic applications, consider using a message queue like RabbitMQ or Redis to decouple webhook receipt from heavy result processing. This ensures your endpoint responds within 5 seconds even under load.