Skip to main content
Webhooks let you receive real-time HTTP POST notifications when events happen in Zeeg. Instead of polling the API, you register a callback URL and Zeeg pushes event data to you the moment something occurs. Zeeg supports seven event types:

Setting up webhooks

Create a webhook subscription by sending a POST 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 a token 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

Store inviteeUuid (and eventUuid) on your side. Invitee-related UUIDs are the best identifiers for correlating bookings, cancellations, and reschedules across webhook deliveries, and they ensure future compatibility — especially for Group events.

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

Use conversationId to deduplicate deliveries and booking.uuid to correlate with invitee.scheduled webhook events for the same booking.

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 a POST 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

Zeeg automatically deletes a webhook subscription if any of the following conditions are met:
  • DNS cannot be resolved for the callback URL on every attempt of a delivery, the last one about 8.6 hours after the first.
  • The callback URL returns a 404 Not Found response.
  • The callback URL returns a 410 Gone response.
When a webhook is auto-deleted, the subscription owner is notified by email. Monitor your inbox to avoid missing events silently.

Best practices

  1. Respond within 10 seconds. Return a 2xx status code as fast as possible. A slower response counts as failed and is retried.
  2. Process asynchronously. Queue the payload for background processing rather than doing heavy work inside the request handler.
  3. Use the verification token. Always set a token when creating a webhook and validate it on every incoming request.
  4. 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-Id header to deduplicate, and occurredAt to apply changes in order.
  5. 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.
Last modified on November 20, 2026