Skip to content
Sudomimus

Configure application webhooks

View as Markdown

Application webhooks notify your backend about supported security events. They are useful for reacting quickly, but they are not a replacement for JWKS, introspection, or the normal Sudomimus APIs when you need current authority.

The first supported event is APPLICATION_SIGNING_KEY_ACTIVATED.

Create an endpoint

Section titled “Create an endpoint”

Open the application in with.sudomimus.com, then choose Webhooks.

  1. Enter a name and a public HTTPS endpoint.
  2. Create the webhook and copy its signing secret immediately.
  3. Store the secret in your backend’s secret manager.
  4. Implement signature verification and duplicate handling before the event can trigger a production action.

An application can have up to five endpoints. Viewer members can inspect endpoints and delivery history; Admin and Owner members can create, update, disable, delete, and rotate them.

The signing secret is shown only when the endpoint is created or the secret is rotated. If you lose it, rotate it and update your backend.

Verify every request

Section titled “Verify every request”

Sudomimus sends these headers:

  • Sudomimus-Webhook-Id
  • Sudomimus-Webhook-Timestamp
  • Sudomimus-Webhook-Signature

The signature is v1= followed by the Base64URL HMAC-SHA256 of:

<timestamp>.<exact raw request body>

Verify the signature before parsing the JSON body. Compare signatures in constant time, reject timestamps more than five minutes from your server clock, and keep the webhook ID so duplicate deliveries do not repeat the same action.

Respond and retry safely

Section titled “Respond and retry safely”

Return any 2xx status after accepting the event. Sudomimus retries timeouts, network failures, 408, 429, and 5xx responses. Other 4xx responses stop delivery for that event.

Delivery is at least once, so the same webhook ID can arrive more than once. Make event handling idempotent.

The Webhooks tab shows recent status, attempt count, HTTP status, and a safe failure summary. It does not store or display your response body.

Endpoint requirements

Section titled “Endpoint requirements”

Webhook endpoints must use public HTTPS on the standard TLS port. Redirects, URL credentials, fragments, private network addresses, loopback hosts, and cloud metadata addresses are rejected.

Disable an endpoint before planned maintenance if you do not want pending events sent to it. Updating the URL or rotating the secret also prevents older pending deliveries from being sent with stale configuration.

Section titled “Related”