Event webhooks

The server can deliver the project's events to a webhook as it stores them. Each event type has a page here: what happened, and the event the request carries.

DeliveryCopy Anchor Link

• One POST per event, with Content-Type: application/json. The body is the event as GET /events returns it; its event_type names the page that describes it.
• Any 2xx status acknowledges the event. Any other status, a failed connection, or no response within 10 seconds leaves it undelivered: the server sends it again on its next pass, and holds back the project's later events until it is delivered. Other projects' events keep going.
• Within a project, events arrive in the order they were stored.
• Delivery is at least once, so an event can arrive twice. Drop duplicates by its id.
• A request carries no signature and no credentials.
• Retention deletes events by age, 30 days by default, whether they were delivered or not. An event the webhook hasn't taken by then is lost.

Setting the webhookCopy Anchor Link

The webhook is part of the server's configuration, not of the API, so a project can't register one yet. On a server you run yourself, set it under events.export:

events:
  export:
    enabled: true
    sinks:
      - type: webhook
        url: https://siem.example.com/zitadel/events

The server delivers the events of claimed projects only. A project's events from before its claim go out once it is claimed, and a new webhook URL starts with the oldest event still retained.

Event typesCopy Anchor Link