Why it matters
Webhooks allow Whippy to push event data to your systems the moment something happens. This enables real-time integrations with tools like CRMs, ATS platforms, or internal services without polling the Whippy API. Using webhooks reduces latency, avoids unnecessary API requests, and keeps downstream systems automatically up to date.
Key Concepts
Webhook: A real-time notification mechanism where Whippy sends an HTTP POST request to your system when a subscribed event occurs.
Webhook endpoint: A public HTTPS URL in your system that accepts incoming POST requests from Whippy and processes JSON payloads.
Event: A specific action in Whippy that can trigger a webhook notification, such as a message being sent or a conversation being created.
JSON payload: A structured data object sent in the body of the webhook request that contains details about the event.
API key (webhook signing): The API key selected for a webhook is used to sign webhook requests so your system can verify that incoming events were sent by Whippy.
Webhooks vs API: Webhooks are used when Whippy needs to notify your system automatically. APIs are used when your system needs to actively perform an action in Whippy, such as sending a message, creating a contact, or starting a campaign.
Step-by-Step: Add a Webhook Endpoint
Open Whippy and locate the code icon (two chevrons and a forward slash) in the top navigation bar.
Click the code icon to open the Developers page.
In the left-hand navigation, select Webhooks.
Click Add Endpoint.
In the Add Application modal, enter a clear name for the webhook application.
Add an optional description to explain the purpose of the webhook.
Select an API key from the dropdown list. (This key will be used to sign webhook requests.)
Click Create Application.
On the Update Endpoint page, enter the public HTTPS URL of your webhook endpoint.
Review the available event categories and select the events your endpoint should receive.
Use the Select All Events option if your workflow requires every available event.
Review the generated sample code in the code panel if needed.
Click Save Endpoint to activate the webhook.
Tips and Best Practices
Use descriptive application names so multiple webhooks are easy to identify later.
Subscribe only to the events required for your use case to limit unnecessary payloads.
Ensure your endpoint responds quickly and handles retries appropriately.
Always verify webhook signatures using the selected API key.
Use APIs and webhooks together. Use APIs to send or create data, and webhooks to receive outcomes and updates.
Troubleshooting
Issue | Possible Cause | Fix |
Endpoint does not receive requests | URL is not publicly accessible | Deploy the endpoint to a public HTTPS URL |
No events are delivered | Events not selected | Edit the endpoint and select the required events |
Signature verification fails | Wrong API key used | Confirm the selected API key matches your verification logic |
Webhook inactive | Application disabled | Re-enable the application from the Webhooks page |
Unexpected payloads | Too many events subscribed | Reduce event subscriptions to only required categories |