Skip to content

Webhooks

  • Permission: webhooks:write (Admin, Security admin, Super admin). webhooks:read to view.
  • An HTTPS endpoint that accepts POST with a JSON body.
  1. Go to Organization › Webhooks and choose Add endpoint.
  2. Enter a Name and the URL, and choose the Events.
  3. Choose Save endpoint, then Copy the signing secret. It starts whsec_ and is shown once.
  4. Choose Send test event to check delivery.
Event When
install.issue_opened A new install issue opens
install.issue_regressed A resolved issue fails again
install.issue_threshold_exceeded An issue passes your affected-device threshold
sso.break_glass_started Support turned SSO enforcement off for a limited time
sso.break_glass_ended That window ended
sso.policy_drift_corrected The sign-in policy was changed in ZITADEL and put back

Events carry no host names, device IDs, user names or command lines. Follow the links back into EndpointWorks for details.

Each request has an EndpointWorks-Signature: t=<unix time>,v1=<hex> header.

  1. Read t and every v1 value.
  2. Refuse the request if t is more than 300 seconds from now.
  3. Compute HMAC-SHA256 of <t>.<raw body> with the whole whsec_… secret as the key.
  4. Accept if it matches any v1, compared in constant time.

Delivery is at least once and not ordered. Deduplicate on the envelope id (also in EndpointWorks-Event-Id).

Choose Rotate secret. Keep the old secret signing for a short overlap: during it, each request carries two signatures, the new secret’s first.

Delivery log shows each attempt. Redeliver sends one again.