Webhooks

Subscribing

A subscription has a name, a destination URL, a signing secret, an on-off switch, the events it wants, and optionally the extensions or numbers it is limited to. The URL must be https on the public internet. Create it in the API or in the portal: the company's Settings page carries a Webhooks panel behind a Webhooks toggle, visible to a login with the Company Edit permission, and it reads and writes the same list the API does. The secret is shown when the subscription is created and never again, so store it then. Several subscriptions per company are fine: call events to one system, message events to another.

The events

• call.started, call.answered, call.ended, within seconds of each step, and call.transcription, which fires when the transcript and summary are ready, usually minutes after the call and sometimes hours on a busy day.
• message.sent for a text sent from the API or the portal, message.received, message.status_updated, all within seconds.
• fax.sent, fax.received, fax.delivered, fax.failed, within a minute of the fax being logged.

Anything outside that list is refused when the subscription is created, with the allowed list in the error. Subscribe to only what you need. Two limits to know. fax.delivered and fax.failed fire only when the result is known as the fax is logged, so read a later result from the fax list. call.transcription is skipped when a transcript is still not ready after six hours or cannot be matched to its call.

Verifying a delivery

Every delivery carries two headers. X-Vocatech-Event names the event. X-Vocatech-Signature reads t=<timestamp>,v1=<signature>, where the signature is an HMAC-SHA256, keyed with your secret, over the string made of t=, the timestamp, a period, and the raw request body. Compute the same thing on your side, compare in constant time, and reject anything that does not match or whose timestamp is more than five minutes off. The exact payloads are in the developer guide.

Responding, and retries

Return a 2xx within five seconds and do the heavy work afterwards; queue the event and answer, rather than making the delivery wait on a database write. Anything else, a redirect included, is treated as a failure and retried four more times over roughly the next three hours. Failed deliveries are listed for the whole account at GET /v1/webhooks/failures for seven days. There is no replay, so fill a gap from the call, message and fax lists. A test send fires a synthetic event at your endpoint so you can check the signature and the response before going live. Handle the same event arriving twice: when your endpoint comes back after an outage it gets a burst, and the event id is the key to dedupe on.

Message events without the rest

A metered messaging key can manage subscriptions to the three message events only; the call, transcription and fax events need the company's standard key. See texting from your own software and REST API basics.