Setting up webhooks
Create a webhook subscription by sending aPOST request to /webhooks.
Required fields
Optional fields
Scope explained
user— You only receive events related to your own scheduling pages.organization— You receive events for all members of your organization. Requires an API token belonging to an admin or owner.
routing_form.submitted and ai_agent.call_completed deliver to organization-scoped webhooks only. Subscribing a user-scoped webhook to either is rejected with a 422, at creation and on every later update — scope cannot change once a webhook exists.
Example
Response
Verifying webhook origin
If you provide atoken when creating the webhook subscription, Zeeg sends it in the Token header of every webhook request. Use this value to verify that incoming requests actually come from Zeeg and not a third party.
Python
Event payloads
invitee.scheduled / invitee.cancelled / invitee.withdrawn / invitee.no_show / invitee.handed_over
All five event types share the same payload structure. Cancellation-specific, no-show-specific, reschedule-specific and handover-specific fields are populated only when relevant.Key fields
Handovers
invitee.handed_over fires on every handover. When the booking can move as it is, it keeps its eventUuid and inviteeUuid and nothing else is sent. When Zeeg has to re-create the booking under the new host, because of its calendar entry or its meeting link, you also receive invitee.cancelled (with rescheduled: true) for the old booking and invitee.scheduled for the new one. The new booking has new ids, and oldEventUuid and oldInviteeUuid point at the old one. In both cases the invitee.handed_over payload describes the booking as it is after the handover. Each event is delivered on its own, so invitee.handed_over can arrive before the invitee.scheduled of the new booking: match the two on inviteeUuid.
The workspace’s webhooks, the new host’s webhooks and the previous host’s webhooks all receive invitee.handed_over.
routing_form.submitted
Key fields
ai_agent.call_completed
Alpha Fired once when an AI agent call reaches a terminal state (answered, voicemail, not answered, busy, or unknown). Contains the call outcome, transcript summary, any data the agent collected from the caller, actions the agent executed, and the booking created during the call (if any).Key fields
Managing webhooks
Replace
{scope} with user or organization.
You can also manage webhooks from the Zeeg dashboard:
Account Settings > Webhooks
Delivery and retries
Each delivery is aPOST with a JSON body. Zeeg waits up to 10 seconds for your response and counts any 2xx status as delivered. Redirects are not followed.
When a delivery times out, the connection fails, the callback domain does not resolve, or your endpoint answers 408, 429 or a 5xx status, Zeeg retries it up to five more times: after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. Any other 4xx status ends the delivery without a retry; 404 and 410 also delete the subscription (see below). Each subscription retries on its own, so a failing endpoint never delays or repeats a delivery to another one. A pending retry is dropped when its subscription is deleted or stops listening for the event. An ai_agent.call_completed delivery for an agent that does not save transcripts gets one attempt only, so the transcript is never kept waiting for a retry.
Every delivery carries a Zeeg-Delivery-Id header that stays the same across its retries. If you see the same value twice, you have already received that delivery.
Retries mean deliveries can arrive out of order: an invitee.scheduled retried after an hour can arrive after the invitee.cancelled for the same booking. Apply the delivery with the newest occurredAt, or read the booking’s current state from GET /scheduled-events/{uuid}.
Auto-deletion
Best practices
- Respond within 10 seconds. Return a
2xxstatus code as fast as possible. A slower response counts as failed and is retried. - Process asynchronously. Queue the payload for background processing rather than doing heavy work inside the request handler.
- Use the verification token. Always set a
tokenwhen creating a webhook and validate it on every incoming request. - Handle duplicates idempotently. A retried delivery can reach you twice, for example when your endpoint processed it but answered after 10 seconds. Use the
Zeeg-Delivery-Idheader to deduplicate, andoccurredAtto apply changes in order. - Monitor for auto-deletion emails. If your endpoint goes down and Zeeg deletes the subscription, you will only know through the notification email. Set up alerting on your side.