Webhook Management

Overview

The Webhook Management API provides endpoints for configuring and managing webhook endpoints for event notifications. You can notify external systems of events such as user creation, login, and role changes.

Endpoint List

Method	Endpoint	Description
GET	/api/admin/webhooks	List webhooks
GET	/api/admin/webhooks/:id	Get webhook details
POST	/api/admin/webhooks	Create webhook
PUT	/api/admin/webhooks/:id	Update webhook
DELETE	/api/admin/webhooks/:id	Delete webhook
POST	/api/admin/webhooks/:id/test	Test webhook
GET	/api/admin/webhooks/:id/deliveries	Get delivery history
POST	/api/admin/webhooks/:id/deliveries/:deliveryId/retry	Retry delivery

---

List Webhooks

Retrieve a list of configured webhooks.

Endpoint

GET /api/admin/webhooks

Query Parameters

Parameter	Type	Required	Description
limit	integer	-	Number of items (default: 20)
cursor	string	-	Pagination cursor
status	string	-	Filter by status (active, inactive)

Request Example

curl -X GET "https://{tenant-domain}/api/admin/webhooks" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "webhook_abc123",
      "name": "User Events",
      "url": "https://api.example.com/webhooks/authrim",
      "events": ["user.created", "user.updated", "user.deleted"],
      "status": "active",
      "success_rate": 99.5,
      "last_triggered_at": 1706054400,
      "created_at": 1705881600
    }
  ],
  "total": 3
}

---

Get Webhook Details

Retrieve detailed information for a specified webhook.

Endpoint

GET /api/admin/webhooks/:id

Path Parameters

Parameter	Type	Required	Description
id	string	✓	Webhook ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/webhooks/webhook_abc123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "webhook_abc123",
  "name": "User Events",
  "description": "User-related event notifications",
  "url": "https://api.example.com/webhooks/authrim",
  "events": ["user.created", "user.updated", "user.deleted"],
  "status": "active",
  "headers": {
    "X-Custom-Header": "custom-value"
  },
  "timeout": 30,
  "retry_policy": {
    "max_retries": 3,
    "retry_interval": 60
  },
  "filters": {
    "user.created": {
      "roles": ["admin"]
    }
  },
  "success_rate": 99.5,
  "total_deliveries": 1250,
  "failed_deliveries": 6,
  "last_triggered_at": 1706054400,
  "last_success_at": 1706054400,
  "last_failure_at": 1705968000,
  "created_at": 1705881600,
  "updated_at": 1706054400
}

---

Create Webhook

Create a new webhook.

Endpoint

POST /api/admin/webhooks

Request Body

Field	Type	Required	Description
name	string	✓	Webhook name
url	string	✓	Endpoint URL
events	string[]	✓	Events to subscribe to
description	string	-	Description
secret	string	-	Secret for signing
headers	object	-	Custom headers
timeout	integer	-	Timeout in seconds (default: 30)
retry_policy	object	-	Retry policy
filters	object	-	Event filters

Request Example

curl -X POST "https://{tenant-domain}/api/admin/webhooks" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Security Events",
    "url": "https://siem.example.com/webhooks/authrim",
    "events": ["auth.login", "auth.login_failed", "auth.logout", "security.alert"],
    "secret": "webhook_secret_123",
    "headers": {
      "X-Source": "authrim"
    },
    "retry_policy": {
      "max_retries": 5,
      "retry_interval": 30
    }
  }'

Response Example

{
  "id": "webhook_xyz789",
  "name": "Security Events",
  "url": "https://siem.example.com/webhooks/authrim",
  "events": ["auth.login", "auth.login_failed", "auth.logout", "security.alert"],
  "status": "active",
  "created_at": 1706140800
}

---

Update Webhook

Update an existing webhook.

Endpoint

PUT /api/admin/webhooks/:id

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/webhooks/webhook_abc123" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["user.created", "user.updated", "user.deleted", "user.suspended"],
    "status": "active"
  }'

---

Delete Webhook

Delete a webhook.

Endpoint

DELETE /api/admin/webhooks/:id

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/webhooks/webhook_abc123" \
  -H "Authorization: Bearer {token}"

---

Test Webhook

Test the webhook configuration. A test event will be sent.

Endpoint

POST /api/admin/webhooks/:id/test

Request Body

Field	Type	Required	Description
event	string	-	Event type to test

Request Example

curl -X POST "https://{tenant-domain}/api/admin/webhooks/webhook_abc123/test" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "user.created"
  }'

Response Example (Success)

{
  "success": true,
  "response_status": 200,
  "response_time_ms": 150,
  "response_body": "{\"received\": true}"
}

Response Example (Failure)

{
  "success": false,
  "error": "Connection timeout",
  "response_time_ms": 30000
}

---

Get Delivery History

Retrieve webhook delivery history.

Endpoint

GET /api/admin/webhooks/:id/deliveries

Query Parameters

Parameter	Type	Required	Description
limit	integer	-	Number of items (default: 50)
cursor	string	-	Pagination cursor
status	string	-	Filter by status (success, failed, pending)
event	string	-	Filter by event type

Request Example

curl -X GET "https://{tenant-domain}/api/admin/webhooks/webhook_abc123/deliveries?status=failed" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "delivery_abc123",
      "event": "user.created",
      "status": "failed",
      "attempt": 3,
      "response_status": 500,
      "response_time_ms": 2500,
      "error": "Internal Server Error",
      "request_body": {
        "event": "user.created",
        "timestamp": "2024-01-22T10:30:00Z",
        "data": {
          "user_id": "usr_xyz789"
        }
      },
      "triggered_at": 1706054400,
      "completed_at": 1706054403
    }
  ],
  "total": 6,
  "cursor": null
}

---

Retry Delivery

Manually retry a failed delivery.

Endpoint

POST /api/admin/webhooks/:id/deliveries/:deliveryId/retry

Path Parameters

Parameter	Type	Required	Description
id	string	✓	Webhook ID
deliveryId	string	✓	Delivery ID

Request Example

curl -X POST "https://{tenant-domain}/api/admin/webhooks/webhook_abc123/deliveries/delivery_abc123/retry" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "delivery_abc123",
  "status": "pending",
  "retry_at": 1706140800
}

---

Event List

User Events

Event	Description
user.created	User created
user.updated	User updated
user.deleted	User deleted
user.suspended	User suspended
user.unsuspended	User unsuspended

Authentication Events

Event	Description
auth.login	Login success
auth.login_failed	Login failed
auth.logout	Logout
auth.password_changed	Password changed
auth.mfa_enabled	MFA enabled

Security Events

Event	Description
security.alert	Security alert
security.suspicious_activity	Suspicious activity

Role & Permission Events

Event	Description
role.assigned	Role assigned
role.unassigned	Role unassigned
policy.created	Policy created
policy.updated	Policy updated

---

Webhook Signature

Webhook requests include signature headers:

X-Authrim-Signature: sha256=xxxxxxxxxxxxxxxxxxxx
X-Authrim-Timestamp: 1706140800

Signature verification:

const crypto = require('crypto');

function verifySignature(payload, signature, secret, timestamp) {
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return `sha256=${expectedSignature}` === signature;
}