Managing Webhooks

Webhooks allow Auris to notify your external systems when authentication events occur — such as user creation, login, password changes, role assignments, and more. Instead of polling the Auris API for changes, your server receives real-time HTTP POST notifications with event details.

Access webhook management at Console → Settings → Webhooks.

Webhook Overview

The Webhooks page shows all configured webhook endpoints for your tenant:

Creating a Webhook

Webhook Secret

Every webhook is assigned a signing secret upon creation. This secret is used to generate HMAC-SHA256 signatures for each delivery, allowing your server to verify that incoming webhooks genuinely originate from Auris.

Viewing the Secret

The signing secret is displayed once immediately after webhook creation in a confirmation dialog. It is prefixed with whsec_ for easy identification:

whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Copy the secret and store it securely in your application’s environment variables. The secret is not shown again after you dismiss the dialog.

Verifying Webhook Signatures

Each webhook delivery includes two headers for signature verification:

Verification steps on your server:

1. Read the X-Webhook-Timestamp header
2. Verify the timestamp is within an acceptable window (for example, 5 minutes) to prevent replay attacks
3. Compute HMAC-SHA256(timestamp + "." + requestBody, webhookSecret)
4. Compare the computed signature with the X-Webhook-Signature header

Example verification in Node.js:

import { createHmac, timingSafeEqual } from 'crypto'
 
function verifyWebhook(
  body: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // Check timestamp freshness (5-minute window)
  const now = Math.floor(Date.now() / 1000)
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return false // Too old or too far in the future
  }
 
  // Compute expected signature
  const payload = `${timestamp}.${body}`
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
 
  // Constant-time comparison to prevent timing attacks
  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Testing Webhooks

Before deploying to production, verify that your endpoint correctly receives and processes webhook payloads.

Send Test Event

On the webhook detail page, click the Test button. Auris sends a test event to the configured URL with a sample payload:

{
  "event": "webhook.test",
  "timestamp": "2025-02-10T08:15:00Z",
  "data": {
    "message": "This is a test webhook delivery from Auris."
  }
}

The test delivery appears in the Deliveries log, so you can verify the response status code and see any error messages.

Using Webhook Testing Tools

For development, you can use a webhook testing service like webhook.site  or ngrok  to receive and inspect webhook payloads:

1. Create a temporary URL using your testing tool
2. Set that URL as the webhook endpoint in the Console
3. Trigger events (for example, create a test user)
4. Inspect the received payload in the testing tool
5. Update the webhook URL to your production endpoint when ready

Viewing Deliveries

Each webhook endpoint has a delivery log showing every event sent to it.

Access the delivery log by clicking any webhook in the list to open the detail page, then scrolling to the Deliveries section.

Delivery Statuses

Click any delivery row to see the full details:

• Request payload: The JSON body sent to your endpoint
• Response body: The response returned by your endpoint (first 1 KB)
• Response headers: HTTP headers returned
• Error message: If the delivery failed, the specific error

Retrying Failed Deliveries

Auris automatically retries failed deliveries (5xx, timeout, network errors) with exponential backoff:

After 3 failed attempts, the delivery is marked as failed and no further automatic retries occur.

Manual Retry

To manually retry a failed delivery:

1. Open the webhook detail page
2. Find the failed delivery in the log
3. Click the Retry button on that delivery row

The manual retry sends the exact same payload to the current webhook URL. If you have changed the URL since the original delivery, the retry goes to the new URL.

Rotating Secrets

If you suspect a webhook secret has been compromised, or if you need to rotate secrets as part of a security policy, you can generate a new secret:

Important: Rotation is immediate. As soon as you rotate, the old secret is invalid and all subsequent deliveries are signed with the new secret. If your endpoint is still configured with the old secret, it will reject deliveries until you update it. Plan for a brief window of failed deliveries during the rotation.

To minimize disruption:

1. Update your endpoint code to accept signatures from either the old or new secret
2. Rotate the secret in the Console
3. After confirming deliveries succeed with the new secret, remove the old secret from your endpoint code

Enabling and Disabling Webhooks

Each webhook has an Active toggle on its detail page. When disabled:

• No events are delivered to the endpoint
• The webhook configuration is preserved (URL, events, secret)
• No deliveries appear in the log while disabled
• Re-enabling resumes deliveries for new events (events that occurred while disabled are not replayed)

Use this to temporarily pause deliveries during endpoint maintenance without losing the webhook configuration.

Event Categories Overview

Auris supports over 50 webhook event types, organized into the following categories:

Each event payload follows a consistent structure:

{
  "event": "user.created",
  "timestamp": "2025-02-10T08:15:00Z",
  "tenantId": "acme-corp",
  "data": {
    // Event-specific payload
  }
}

The data field varies per event type and contains the relevant entity data at the time of the event.

Related Guides

• Webhook Integration — Developer Guide — Building a webhook consumer with signature verification
• Actions Engine — Alternative for in-flow logic (runs during auth, not after)
• Audit Logs — View all authentication events with full audit trails