Webhooks
Before you begin
Section titled “Before you begin”- Permission:
webhooks:write(Admin, Security admin, Super admin).webhooks:readto view. - An HTTPS endpoint that accepts
POSTwith a JSON body.
Add an endpoint
Section titled “Add an endpoint”- Go to Organization › Webhooks and choose Add endpoint.
- Enter a Name and the URL, and choose the Events.
- Choose Save endpoint, then Copy the signing secret. It starts
whsec_and is shown once. - Choose Send test event to check delivery.
Events
Section titled “Events”| 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.
Verify a signature
Section titled “Verify a signature”Each request has an EndpointWorks-Signature: t=<unix time>,v1=<hex> header.
- Read
tand everyv1value. - Refuse the request if
tis more than 300 seconds from now. - Compute HMAC-SHA256 of
<t>.<raw body>with the wholewhsec_…secret as the key. - 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).
Rotate the secret
Section titled “Rotate the secret”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
Section titled “Delivery log”Delivery log shows each attempt. Redeliver sends one again.