Webhooks

Webhooks give application developers the ability to listen for all audit events using an HTTP endpoint. Events are sent to your endpoint using the same format as they are submitted in the audit API.

Managing webhook subscriptions

Webhooks are managed with a custom REST resource with the following methods. Use of these methods requires the authenticated user to have the view-events and manage-events permissions. If you are using one of the supported languages, we recommend using our SDKs rather than building the requests yourself.

Path	Method	Payload	Returns	Description
/auth/realms/:realm/webhooks	GET		List of webhook objects	Get webhooks
/auth/realms/:realm/webhooks	POST	Webhook object	201	Create webhook
/auth/realms/:realm/webhooks/:id	GET		Webhook object	Get webhook
/auth/realms/:realm/webhooks/:id	PUT	Webhook object	204	Update webhook
/auth/realms/:realm/webhooks/:id	DELETE		204	Delete webhook

The webhook object has this format:

{
  "id": "475cd2fd-3ca8-4c22-b5c8-c8b8927dcc10",
  "enabled": "true",
  "url": "https://example.com/some/webhook",
  "secret": "ofj09saP4",
  "eventTypes": ["*"],
  "createdBy": "ff730b72-a421-4f6e-9e4e-7fc7f53bac88",
  "createdAt": "2021-04-21T18:25:43-05:00"
}

For creating and updating of webhooks, id, createdBy and createdAt are ignored. secret is not sent when fetching webhooks.

Event types

The eventTypes variable is an array of expressions that match the type of event. It can contain a wildcard, such as * (send all events), access.* (send all access events), or admin.CLIENT-* (send all admin events related to the CLIENT resource type). It can also be a specific event type such as admin-USER-CREATE (only send user creation events).

Enable Webhooks in Admin UI

Enable webhook events in the Admin UI by going to (Configure) Realm Settings > Events (tab) > Event Listeners, in the Event listeners dropdown select ext-event-webhook and Save.

Retries

Webhooks are sent using an automatic exponential backoff if there is not a 2xx response. The sending tasks are scheduled after the transaction which produced the event has been committed, so there is no question if the activity has occured.

Client performance

It is expected that the client will immediately send a 2xx response when receiving an event. If it does not, requests can become backed up and you may miss events because the server will not retry forever.

Example

To create a webhook for all events on the test realm:

POST /auth/realms/test/webhooks

{
  "enabled": "true",
  "url": "https://exxxxxxxxxxxxxx.m.pipedream.net",
  "secret": "A3jt6D8lz",
  "eventTypes": [
    "*"
  ]
}

Testing

Pipedream is a great way to test your webhooks, and use the data to integrate with your other applications.