Webhooks allow you to receive real-time data from Diaform by sending HTTP POST requests to your server when specific events occur. This enables you to build custom integrations, trigger workflows, or sync data with your own systems.
What Are Webhooks?#
Webhooks are HTTP POST requests sent to a URL you specify whenever an event occurs in Diaform. Instead of polling our API to check for new data, we push it to you automatically.
Supported Events#
Currently, Diaform supports the following webhook event:
conversation.completed— Fires when an interview finishes and the AI-generated summary is ready
Additional events will be added in future releases.
Setting Up a Webhook#
Navigate to Organization Settings and select the Webhooks tab.
Enter your endpoint URL in the input field. The URL must use HTTPS for security.
Click Add webhook to create the webhook.
A unique webhook secret is automatically generated. This secret is used to verify that incoming requests are genuinely from Diaform. Store it securely — you'll need it to validate webhook signatures.
Your webhook secret is shown only once when the webhook is created. Store it securely in your server's environment variables or secrets manager. If you lose it, you'll need to delete and recreate the webhook.
Managing Webhooks#
From the Webhooks page, you can:
- View and copy the webhook secret — Displayed once after creation
- Toggle active/inactive — Temporarily pause webhook delivery without deleting the endpoint
- Delete webhooks — Remove endpoints you no longer need
Multiple Webhooks#
You can add multiple webhook endpoints to the same organization. When an event occurs, all active webhooks will receive the payload in parallel.
Delivery Details#
- Webhooks are sent in parallel to all active endpoints
- Each request has a 5-second timeout
- Failed deliveries are logged but do not retry (fire-and-forget)
- Ensure your endpoint responds with a 2xx status code to acknowledge receipt
For information on the payload structure, see Webhook Payload Reference. To verify webhook authenticity, see Verifying Webhook Signatures.