Webhooks
Using the Webhooks view in the Auth.it Dashboard, you can configure Auth.it to send audit events to external HTTP endpoints. This enables integration with your applications or third-party systems for security monitoring, compliance logging, automation, or analytics.
Auth.it tracks multiple types of events that fall into two categories: access events (for user activity) and admin events (for administrator actions).
The Audit Logs page lists common access events and explains the structure of admin events.
Events are sent to your endpoints in the same JSON format used by Auth.it’s own audit logs.
Adding a webhook
To add a new webhook endpoint, click Add Webhook at the top right. In the Add Webhook dialog, enter the URL of your server’s webhook event handler and select whether to send user events, admin events, or both.
You can also create and manage webhooks using the Auth.it API.
Security
After creating a webhook, navigate to its detail page by clicking its entry in the list of webhooks. There you will find a masked secret that you can copy to the clipboard by clicking the icon next to the secret value. This is known as a shared secret, and can be used to verify that the webhook payload was sent by Auth.it and is authentic.
Once you receive the webhook payload on your server, you can verify it using a keyed-HMAC (Hash-based Message Authentication Code) algorithm. Auth.it signs the message with the HmacSHA256 signature algorithm and, according to RFC2104, includes the signature in the X-Keycloak-Signature header.
You can find many libraries for your server language or framework that make it possible to validate the signature using the message payload and shared secret. Some examples include:
- JavaScript/TypeScript: the built-in
cryptomodule in Node.js. - Python: the built-in
hmacandhashlibmodules in the Python standard library. - Java:
javax.crypto.Macandjavax.crypto.spec.SecretKeySpecin the JDK. - C#:
System.Security.Cryptography.HMACSHA256.
Retries
Auth.it sends each event after the transaction that produced it has been committed. Auth.it expects the client to immediately return a 2xx response when receiving an event. If a 2xx response is not returned, the event is automatically resent with exponential backoff.
If necessary, you can manually resend an event by going to the webhook’s detail page, opening the three-dot menu to the right of an event entry, and clicking Resend:
