Webhooks API on AuthOS Docs | Auth Operating System API and SDK Guides

Webhook Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Webhook Management

POST /api/organizations/:org_slug/webhooks

Create a new webhook for an organization. The webhook secret is generated automatically and returned only once upon creation.

Authentication: Required (Organization Management JWT)

Permissions: Organization owner or admin

Path Parameters:

Parameter	Type	Description
`org_slug`	string	Organization slug

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Webhook name (must be unique within organization)
`url`	string	Yes	Target URL for webhook deliveries (must start with http:// or https://)
`events`	array of strings	Yes	List of event types to subscribe to (at least one required)

Request Headers:

Webhook Signing and Verification

Mon, 01 Jan 0001 00:00:00 +0000

Security

Signature Verification

The implementation adds signature and timestamp headers to webhook delivery attempts. Recipients must verify the exact raw signed bytes, compare signatures safely, enforce a timestamp window, and deduplicate delivery IDs. Public delivery/replay abuse-case evidence is still being expanded.

Headers:

X-Webhook-Signature: HMAC-SHA256 signature of the payload
X-Webhook-Timestamp: Unix timestamp in seconds since epoch (UTC)

Signature Format:

sha256={hmac_hex_digest}

Verification Example (Node.js):

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  // Create HMAC using webhook secret
  const hmac = crypto.createHmac('sha256', secret);

  // Update with stringified payload
  hmac.update(JSON.stringify(payload));

  // Generate expected signature
  const expectedSignature = `sha256=${hmac.digest('hex')}`;

  // Use timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js middleware example
app.post('/webhooks/sso', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = req.body;

  // Limit the replay window; also persist and deduplicate delivery IDs
  const currentTime = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTime - timestamp) > 300) {
    return res.status(400).json({ error: 'Timestamp too old' });
  }

  // Verify signature
  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook payload
  console.log('Received event:', payload.event);
  res.status(200).json({ status: 'received' });
});

Verification Example (Python):

Webhook Delivery and Retries

Mon, 01 Jan 0001 00:00:00 +0000

Webhook Delivery

GET /api/organizations/:org_slug/webhooks/:webhook_id/deliveries

Get paginated delivery history for a webhook, including request payload, response status, and retry information.

Authentication: Required (Organization Management JWT)

Permissions: Organization owner or admin

Path Parameters:

Parameter	Type	Description
`org_slug`	string	Organization slug
`webhook_id`	string	Webhook ID

Query Parameters:

Parameter	Type	Required	Default	Description
`page`	integer	No	1	Page number (minimum: 1)
`limit`	integer	No	50	Results per page (maximum: 100)
`event_type`	string	No	-	Filter by event type
`delivered`	boolean	No	-	Filter by delivery status (true/false)

Request Headers:

Webhook Event Catalog

Mon, 01 Jan 0001 00:00:00 +0000

Use the event-types endpoint for the identifiers supported by the running deployment. For the maintained static payload reference, see Webhook Events Reference.

Event Types

GET /api/organizations/:org_slug/webhooks/event-types

Get a list of all available webhook event types with descriptions and categories.

Authentication: Required (Organization Management JWT)

Permissions: Organization owner or admin

Path Parameters:

Parameter	Type	Description
`org_slug`	string	Organization slug

Query Parameters: None

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

curl -X GET https://sso.example.com/api/organizations/acme-corp/webhooks/event-types \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK):

Webhook Receiver Examples

Mon, 01 Jan 0001 00:00:00 +0000

Before implementing a receiver, review signing and verification and delivery and retries.

Complete Workflow Example

1. Create Webhook

curl -X POST https://sso.example.com/api/organizations/acme-corp/webhooks \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Events",
    "url": "https://api.acme.com/webhooks/sso",
    "events": ["user.login.success", "user.signup.success"]
  }'

2. Implement Webhook Endpoint

// Express.js webhook handler
app.post('/webhooks/sso', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body;

  // Verify signature
  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process event
  switch (payload.event) {
    case 'user.login.success':
      console.log(`User ${payload.actor_email} logged in`);
      break;
    case 'user.signup.success':
      console.log(`New user ${payload.actor_email} signed up`);
      // Send welcome email, create account in CRM, etc.
      break;
  }

  res.status(200).json({ status: 'received' });
});

3. Monitor Deliveries

curl -X GET "https://sso.example.com/api/organizations/acme-corp/webhooks/{webhook_id}/deliveries?page=1&limit=50" \
  -H "Authorization: Bearer {jwt}"

4. Handle Failed Deliveries

# Check for failed deliveries
curl -X GET "https://sso.example.com/api/organizations/acme-corp/webhooks/{webhook_id}/deliveries?delivered=false" \
  -H "Authorization: Bearer {jwt}"

# Review error messages and fix endpoint
# Optionally disable webhook while fixing
curl -X PATCH https://sso.example.com/api/organizations/acme-corp/webhooks/{webhook_id} \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Best Practices

Webhook Design

Subscribe only to events you need to reduce traffic
Use descriptive webhook names for easy identification
Implement proper error handling and logging
Return 2xx status codes quickly (process asynchronously)
Use signature verification for security

Endpoint Implementation

Implement idempotency using delivery IDs
Process webhooks in background jobs/queues
Log all webhook deliveries for debugging
Return non-2xx only for invalid requests
Implement rate limiting and request validation

Monitoring & Maintenance

Monitor delivery success rates
Set up alerts for failed deliveries
Review delivery history regularly
Test webhook endpoints before enabling
Document your webhook integrations

Security

Always verify webhook signatures
Validate timestamps to limit the replay window and persist delivery IDs for deduplication
Use HTTPS endpoints only
Store webhook secrets securely
Implement IP allowlisting if possible
Rate limit webhook endpoints

Webhook Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Start with the webhook’s delivery history. Compare the response status, response body, attempt count, next retry time, and delivery error before changing configuration.

Error Responses

Common Errors

400 Bad Request:

{
  "error": "Webhook name cannot be empty",
  "error_code": "BAD_REQUEST",
  "timestamp": "2025-01-15T10:30:00Z"
}

401 Unauthorized:

{
  "error": "Missing or invalid Authorization header",
  "error_code": "UNAUTHORIZED",
  "timestamp": "2025-01-15T10:30:00Z"
}

403 Forbidden:

{
  "error": "Organization admin or owner role required",
  "error_code": "FORBIDDEN",
  "timestamp": "2025-01-15T10:30:00Z"
}

404 Not Found:

{
  "error": "Webhook not found",
  "error_code": "NOT_FOUND",
  "timestamp": "2025-01-15T10:30:00Z"
}

Delivery troubleshooting

Symptom	Check	Action
No attempts appear	Webhook is active and subscribed to the emitted event	Confirm configuration and query the runtime event-types endpoint
Signature validation fails	Raw request bytes, current secret, signature prefix, and comparison lengths	Verify the unmodified body before parsing and use constant-time comparison
Deliveries repeat	`X-Webhook-Delivery-Id` and attempt number	Persist the delivery ID and make processing idempotent
Attempts time out	Receiver latency and synchronous work	Acknowledge quickly and move processing to a durable queue
Retries stop	Attempt count and latest response/error	Repair the receiver, then reconcile critical state through the authoritative API

For security-sensitive failures, re-read signing and verification. For delivery guarantees and retry timing, see delivery and retries.