Webhooks overview

A webhook is a message that BreezeAuth sends to one of your systems as soon as something changes in your organization. For example, BreezeAuth can notify your system the moment a user joins, a group gains a member or an application is removed.

Without webhooks, your systems would have to keep asking BreezeAuth “did anything change?” every few minutes. With webhooks, BreezeAuth tells them, right away.

What you can use webhooks for

• Provision and deprovision accounts. Create an account in an internal system when someone joins the organization, and disable it the moment their membership is deleted.
• Keep access in sync. Mirror group memberships or application assignments into another tool, such as an HR platform, a CRM or a data warehouse.
• Alert your team. Notify your security or IT team when a domain is added or an application’s configuration changes.
• Feed your own audit trail. Record identity changes in your own logging or compliance system.

How it works

1. Something changesA user, group, application, assignment or domain is created, updated or deleted.
2. BreezeAuth signs a messageThe message says what happened and is signed so you can prove it came from BreezeAuth.
3. Your endpoint receives itBreezeAuth sends a POST request to the URL you registered.
4. You acknowledge itYour endpoint replies with a 2xx status within 15 seconds. Otherwise, BreezeAuth tries again.

To start receiving events, someone with permission to manage webhooks registers an endpoint: a URL on your side, plus the list of events it should receive. You can register several webhooks, for example one per system, each with its own selection of events. See Create and manage webhooks.

What a message contains

Each message describes one event and carries only the identifiers of what changed, not the full details. For example, when a user is created, the message tells you the identifier of the new membership but not the person’s name or e-mail. Your system then uses the BreezeAuth API to fetch the current details it needs.

{
  "uuid": "6c1f0f8e-4f5b-4a53-9d0e-2b7c9a1e3f42",
  "organizationsUuid": "0d5a7e3c-8b1f-4c2e-a6d9-5f4e3b2a1c0d",
  "timestamp": "2026-10-13T14:32:05.123Z",
  "type": "membership.created",
  "data": {
    "membershipsUuid": "a3b9c1d2-7e4f-4a6b-8c5d-9e0f1a2b3c4d"
  }
}

This design keeps personal data out of the messages and guarantees that your system always works with up-to-date information, even if messages arrive late or out of order. The complete list of events is in the event catalog.

Key facts at a glance

Topic	Behavior
Standard	Follows the Standard Webhooks specification, with asymmetric signatures.
Transport	HTTP POST with a JSON body (Content-Type: application/json).
Signature	Ed25519, sent in the webhook-signature header. The signing key is identified by the webhook-keyid header.
Source IPs	A fixed, published set of addresses that you can allowlist in your firewall.
Success	Only 2xx responses. Redirects (3xx) are not followed and count as failures.
Timeout	15 seconds per attempt.
Attempts	Up to 3 per event: the first delivery plus 2 retries, after about 5 and 30 seconds.
Delivery guarantee	At least once. The same message may arrive more than once, so your endpoint must ignore duplicates.
Ordering	Not guaranteed. Use the API to read the current state instead of relying on message order.
Monitoring	Every attempt is recorded in the webhook’s Event History in the admin console.

Responsibilities of the receiving system

Webhooks are safe and reliable only if the receiving system follows a few rules. Your developers will find the details in the next pages; in short, the receiver must:

Receive events reliably explains each rule with examples.

For an extra layer of protection, you can also restrict your endpoint so that it only accepts requests from BreezeAuth’s IP addresses.

Next steps

• Create and manage webhooks in the admin console.
• Browse the event catalog to choose which events you need.
• Share Verify signatures and Receive events reliably with the developers building your endpoint.