---
title: Configure application webhooks
description: Receive signed application security events at an HTTPS endpoint.
editUrl: true
head: []
template: doc
sidebar:
  order: 7
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

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

Open the application in [`with.sudomimus.com`](https://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

Sudomimus sends these headers:

- `Sudomimus-Webhook-Id`
- `Sudomimus-Webhook-Timestamp`
- `Sudomimus-Webhook-Signature`

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

```text
<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

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

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.

## Related

- [Application lifecycle](/en-us/with-portal/application-lifecycle/) - take an application live or disable it.
- [Manage token-signing keys](/en-us/with-portal/organizations-and-applications/#manage-token-signing-keys) - the event currently delivered by webhooks.