Skip to main content

Call started

Webhook

Sent when an inbound or outbound agent call attempt begins, before it is answered, including attempts that fail or go unanswered. Builder test calls and the human portion of transferred calls are excluded.

A test sent from Settings > Developers uses the Call ended shape, with event set to test_event.

Delivery​

Add endpoints in Settings > Developers. Each endpoint receives one event type, for all agents or one agent, and starts disabled until you enable it.

Harmony sends a JSON POST to the endpoint URL. Verify the signature, durably accept the event, and return a 2xx status within 10 seconds. Process slower work asynchronously.

Any other status, a timeout, or a connection failure is retried at roughly 60-second intervals, up to five attempts. Retries keep the same webhook-id but may contain updated data. Redirects are not followed.

Verify signatures​

Verify each request with a Standard Webhooks library, the endpoint's signing secret, the raw request body, and the three webhook-* headers. Verification fails on an invalid signature or a timestamp more than five minutes from now. Reject the request when it fails.

import { Webhook } from "standardwebhooks";

const event = new Webhook(signingSecret).verify(rawBody, headers);

Request​

Responses​

Any 2xx status accepts the event. Other statuses are retried.