Perplexity API Webhook Not Triggering: Fix Steps

You set up a webhook in the Perplexity API to receive real-time data, but the endpoint never receives a POST request. This usually happens because of a misconfiguration in the webhook URL, an incorrect event selection, or a network-level block. This article explains why the webhook fails to trigger and provides step-by-step fixes to get it working.

Why the Perplexity API Webhook Does Not Trigger

The Perplexity API sends a POST request to your webhook URL when a specific event occurs, such as a completed search or a new answer. If the webhook does not trigger, one of three things is wrong. First, the URL you provided is unreachable or does not return a 200 OK status within 5 seconds. Second, you subscribed to the wrong event or no event at all. Third, your server or firewall blocks the incoming request from Perplexity servers. The API also sends a test ping when you first save the webhook; if that ping fails, the webhook is disabled automatically.

Common Root Causes in Detail

The most frequent cause is an invalid or expired SSL certificate on your endpoint. Perplexity requires HTTPS and validates the certificate chain. If the certificate is self-signed or expired, the request is dropped. Another common cause is a missing or incorrect event name in the subscription payload. The API accepts only event names documented in the official reference, such as search.completed or answer.created. A typo in the event name silently fails. Finally, rate limiting or IP whitelisting on your side can reject the request before your application processes it.

Steps to Fix a Non-Triggering Webhook

Follow these steps in order. After each step, test the webhook by triggering the event manually or using the API dashboard test function.

Step 1: Verify the Webhook URL and SSL Certificate

1. Check the URL protocol
   The URL must start with https://. HTTP URLs are rejected immediately. Example: https://yourdomain.com/webhook.
2. Test the endpoint manually
   Use a tool like curl or Postman to send a POST request to the URL. The endpoint must return HTTP 200 within 5 seconds. Any other status code or timeout causes the webhook to fail.
3. Validate the SSL certificate
   Open the URL in a browser and click the padlock icon. The certificate must be issued by a trusted CA and not be expired. Self-signed certificates are not allowed.

Step 2: Confirm the Event Subscription

1. Log in to the Perplexity API dashboard
   Go to https://api.perplexity.ai/dashboard and navigate to Webhooks.
2. Inspect the subscribed events
   Click the webhook entry. The list of subscribed events appears. Ensure the event you expect, such as search.completed, is checked.
3. Add missing events
   If the event is missing, click Edit Webhook and check the correct event name from the dropdown. Save the changes.

Step 3: Check Network and Firewall Rules

1. Allow inbound traffic on port 443
   Your server firewall must accept TCP connections on port 443 from all IPs or specifically from the Perplexity IP range. Contact Perplexity support for the current IP list.
2. Disable IP whitelisting temporarily
   If you have an IP whitelist, remove it and test the webhook. If the webhook triggers, add the Perplexity IPs to the whitelist.
3. Review reverse proxy logs
   If you use Nginx or Apache, check the access logs for requests from Perplexity IPs. A missing log entry means the request never reached your server.

Step 4: Test the Webhook Using the Dashboard

1. Use the Send Test button
   In the webhook edit page, click Send Test. The API sends a test payload to your endpoint. If the test succeeds, the webhook status changes to Active.
2. Check the response log
   After the test, the dashboard shows the HTTP status code and response body from your endpoint. A 200 status confirms the webhook is working.
3. Trigger a real event
   Perform an action that matches the subscribed event, such as running a search query. The webhook log should show a new entry within seconds.

If the Webhook Still Does Not Trigger

If you completed all steps and the webhook remains inactive, check these additional failure patterns.

Webhook Shows Disabled After Saving

The API automatically disables a webhook if the initial test ping fails. Re-enable it by clicking Enable in the dashboard, then fix the URL or SSL issue from Step 1. The webhook will be tested again.

Webhook Triggers But Payload Is Empty

An empty payload usually means the event occurred but no data matched the subscription filter. For example, if you subscribe to search.completed but the search returned no results, the payload may contain only metadata. Check the event documentation for the expected payload structure.

Webhook Triggers Only Intermittently

Intermittent failures are often caused by network timeouts or rate limiting. Your endpoint must respond within 5 seconds. If your application processes the request slowly, move the processing to a background job and return 200 immediately. Also check if your hosting provider blocks repeated requests from the same IP.

Perplexity API Webhook Events: Search Completed vs Answer Created

Item	Search Completed	Answer Created
Event name	search.completed	answer.created
Trigger condition	Perplexity finishes a search query	Perplexity generates a final answer from sources
Payload contains	Query text, source count, duration	Answer text, citations, confidence score
Use case	Logging search activity	Storing or forwarding the answer

You can now diagnose and fix a Perplexity API webhook that fails to trigger. Start by verifying the URL and SSL certificate, then check the event subscription and network rules. Use the dashboard test function to confirm each fix. For advanced reliability, set up a retry mechanism in your endpoint and monitor the webhook log for failed deliveries.