Webhooks push Vocatech events to your endpoint the moment they happen. A call ends, your server gets a POST. A message is received, your server gets a POST. No polling. No delay.
Every payload is signed so you can verify it actually came from us. Every failed delivery retries automatically. You configure each endpoint once and forget about it.
Subscribing
Subscriptions are created through the REST API or inside the admin portal. You provide a URL, pick the event types you want, and the system generates a signing secret for that subscription.
Multiple endpoints per company are fine. Send call events to one service and message events to another if that fits your architecture.
Each endpoint must be HTTPS. Plain HTTP is rejected. Self-signed certificates are rejected. Use a real cert.
Event types
Seven event types cover the full call and message lifecycle.
call.startedfires when a call begins ringing.call.answeredfires when someone picks up.call.endedfires when the call hangs up. Most automations hook here.call.transcriptionfires when the AI transcription and summary are ready. This arrives a few seconds after the call ends.message.sentfires when an outbound SMS or WhatsApp leaves your account.message.receivedfires when an inbound message arrives.message.status_updatedfires when a carrier delivery status changes.
Subscribe to only the events you need. Fewer events means less load on your endpoint and faster debugging when something goes wrong.
Signature verification
Every request includes an X-Vocatech-Signature header. The signature is an HMAC-SHA256 of the raw request body, keyed with the signing secret from your subscription.
On your server, compute the same HMAC over the raw body and compare. If it matches, the payload is authentic. If it does not, reject the request.
Each request also includes an X-Vocatech-Timestamp header. Reject any request where the timestamp is more than 5 minutes old. This prevents an attacker from replaying a captured request later.
Responding correctly
Return a 2xx status code within 10 seconds to acknowledge receipt. The body can be empty. We do not care what you return, only that you return quickly.
If your handler does heavy work (database writes, API calls, AI processing), push the event onto a queue and return 200 immediately. Anything else risks a timeout.
Any non-2xx response triggers a retry.
Retry behavior
Failed deliveries retry with exponential backoff. The first retry is a few seconds later. The next is a minute. Then several minutes. Then hours. Retries continue for up to 24 hours before the event is marked failed and dropped.
When your endpoint comes back online, you will get a burst of queued events. Your handler should be idempotent, meaning processing the same event twice should not break anything. Use the event ID as a dedupe key.
Testing a subscription
The portal has a test session feature. Open your subscription, click test, and fire a synthetic event at your endpoint. You see the full request, your response, the signature, and any error.
This is the fastest way to confirm your signature check works and your endpoint returns 2xx in time.
Getting help
Full event schemas are documented at api.vocatech.com/docs. If a webhook is not firing when you expect it to, call 718.395.1550 and we can look at the delivery logs with you.