Webhooks
Webhooks let you send real-time notifications to your own systems whenever something happens in Akol — like a call ending or an appointment being booked.
What Are Webhooks?
When an event occurs (e.g., a call completes), Akol sends an HTTP POST request to a URL you specify. Your server receives the event data and can take action — update a database, trigger a workflow, send a notification, etc.
Accessing Webhooks
Go to Dashboard > Webhooks to manage your webhooks.
Creating a Webhook
- Click Create Webhook
- Fill in the details:
- Name — A friendly name (e.g., “CRM Call Logger”)
- URL — The endpoint that will receive events (must be HTTPS)
- Events — Select which events to subscribe to
- Click Create
A secret key is automatically generated. Use this to verify that incoming requests are genuinely from Akol.
Available Events
Call Events
| Event | Fires When |
|---|---|
call.started | A call begins ringing or connects |
call.ended | A call hangs up (any reason) |
call.completed | A call finishes successfully |
call.missed | A call was not answered |
call.failed | A call failed to connect |
call.transferred | A call was transferred to a human |
Content Events
| Event | Fires When |
|---|---|
transcript.ready | The call transcript is available |
summary.ready | The AI-generated summary is available |
function.called | The AI agent called a tool during a call |
Resource Events
| Event | Fires When |
|---|---|
agent.created | A new agent is created |
agent.updated | An agent’s settings are changed |
agent.deleted | An agent is deleted |
phone_number.purchased | A new phone number is bought |
phone_number.released | A phone number is released |
Secret Key Management
Each webhook has a secret key used to sign payloads. This lets you verify that requests are from Akol, not a third party.
Verifying Signatures
Every webhook request includes an X-Webhook-Signature header. Compare this against a hash of the request body using your secret key to verify authenticity.
Rotating Secrets
If your secret is compromised:
- Click on the webhook
- Click Rotate Secret
- A new secret is generated immediately
- Update your server with the new secret
After rotating a secret, the old secret stops working immediately. Make sure to update your receiving server before or right after rotating.
Testing Webhooks
Click Test on any webhook to send a test payload to your URL. This lets you verify your endpoint is working without waiting for a real event.
The test sends a sample payload for each subscribed event type. Check your server logs to confirm it was received.
Delivery Logs
Each webhook keeps a log of recent deliveries:
- Timestamp — When the event was sent
- Event — Which event type was triggered
- Status code — The HTTP response from your server
- Success/Failure — Whether delivery succeeded
- Response — The response body from your server
Use the logs to debug delivery issues or verify your endpoint is processing events correctly.
Akol expects your endpoint to return a 2xx status code within 30 seconds. If your server doesn’t respond or returns an error, the delivery is marked as failed.
Enabling and Disabling
Toggle a webhook to Inactive to temporarily stop sending events without deleting the webhook. Toggle it back to Active when ready.
Deleting a Webhook
Click Delete to permanently remove a webhook and all its delivery logs.
Tips
- Use HTTPS — Webhook URLs must be HTTPS for security
- Respond quickly — Process webhook data asynchronously. Return a 200 immediately, then process the data
- Verify signatures — Always verify the webhook signature to prevent spoofing
- Monitor delivery logs — Check periodically to make sure deliveries are succeeding
- Use test payloads — Test your endpoint before going live to catch issues early