Setup

Create and manage webhook endpoint configurations for your application through the YorAuth API.

Authentication

The webhook management API supports two authentication methods depending on your context:

• SDK / programmatic access — JWT Bearer token with the webhooks:manage permission, via /api/v1/applications/{applicationId}/webhooks
• Dashboard — Sanctum cookie session (used by the YorAuth dashboard), via /api/dashboard/applications/{applicationId}/webhooks

All examples on this page use the v1 API with a JWT Bearer token.

Create a Webhook

Register a new endpoint to receive events.

POST /api/v1/applications/{applicationId}/webhooks

Request body:

curl -X POST https://api.yorauth.com/api/v1/applications/{applicationId}/webhooks \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/yorauth",
    "events": ["user.created", "user.login", "role.assigned", "role.removed"]
  }'

Response 201 Created:

{
  "data": {
    "id": "9d4e1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "url": "https://example.com/webhooks/yorauth",
    "secret": "wh_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "events": ["user.created", "user.login", "role.assigned", "role.removed"],
    "is_active": true,
    "created_at": "2026-02-25T12:00:00+00:00"
  }
}

List Webhooks

Retrieve all webhook configurations for an application.

GET /api/v1/applications/{applicationId}/webhooks

curl https://api.yorauth.com/api/v1/applications/{applicationId}/webhooks \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "data": [
    {
      "id": "9d4e1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
      "url": "https://example.com/webhooks/yorauth",
      "events": ["user.created", "user.login"],
      "is_active": true,
      "created_at": "2026-02-25T12:00:00+00:00",
      "updated_at": "2026-02-25T12:00:00+00:00"
    }
  ]
}

Note: the secret is never included in list or show responses.

Get a Webhook

Retrieve a single webhook configuration by ID.

GET /api/v1/applications/{applicationId}/webhooks/{webhookId}

curl https://api.yorauth.com/api/v1/applications/{applicationId}/webhooks/9d4e1a2b-... \
  -H "Authorization: Bearer your-api-key"

Response 200 OK:

{
  "data": {
    "id": "9d4e1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "url": "https://example.com/webhooks/yorauth",
    "events": ["user.created", "user.login"],
    "is_active": true,
    "created_at": "2026-02-25T12:00:00+00:00",
    "updated_at": "2026-02-25T12:00:00+00:00"
  }
}

Update a Webhook

Modify the URL, event subscriptions, or active state of an existing webhook. All fields are optional — only include the ones you want to change.

PUT /api/v1/applications/{applicationId}/webhooks/{webhookId}

Request body:

curl -X PUT https://api.yorauth.com/api/v1/applications/{applicationId}/webhooks/9d4e1a2b-... \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["user.created", "user.login", "mfa.enabled", "mfa.disabled"],
    "is_active": true
  }'

Response 200 OK:

{
  "data": {
    "id": "9d4e1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "url": "https://example.com/webhooks/yorauth",
    "events": ["user.created", "user.login", "mfa.enabled", "mfa.disabled"],
    "is_active": true,
    "created_at": "2026-02-25T12:00:00+00:00",
    "updated_at": "2026-02-25T12:05:00+00:00"
  }
}

Delete a Webhook

Permanently remove a webhook configuration and all associated delivery history.

DELETE /api/v1/applications/{applicationId}/webhooks/{webhookId}

curl -X DELETE https://api.yorauth.com/api/v1/applications/{applicationId}/webhooks/9d4e1a2b-... \
  -H "Authorization: Bearer your-api-key"

Response 204 No Content

URL Requirements

YorAuth validates webhook URLs before saving them to protect against Server-Side Request Forgery (SSRF) attacks.

Requirements:

• HTTPS only — HTTP URLs are rejected.
• Public hostname — The URL must not resolve to a private, loopback, or reserved IP address. This includes localhost, 127.0.0.1, ::1, 0.0.0.0, host.docker.internal, kubernetes.default, and metadata.google.internal.
• Valid DNS — The hostname must resolve to at least one IP address.
• All resolved IPs must be public — If a hostname resolves to any private or reserved IP, the URL is rejected.

DNS rebinding protection also runs at delivery time, so even if a hostname resolves to a public IP at registration, it is re-validated immediately before each delivery attempt.

Dashboard-Only Endpoints

The following endpoints are available only through the dashboard API (Sanctum auth):

Rotate Secret

Generates a new 64-character signing secret. The old secret stops working immediately.

curl -X POST https://api.yorauth.com/api/dashboard/applications/{applicationId}/webhooks/9d4e1a2b-.../rotate-secret \
  -H "Cookie: <sanctum-session>"

Response 200 OK:

{
  "data": {
    "secret": "wh_live_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
  }
}

Send a Test Delivery

Dispatches a webhook.test event to verify your endpoint is reachable and correctly verifying signatures.

curl -X POST https://api.yorauth.com/api/dashboard/applications/{applicationId}/webhooks/9d4e1a2b-.../test \
  -H "Cookie: <sanctum-session>"

Response 200 OK:

{
  "data": {
    "delivery_id": "ab12cd34-...",
    "message": "Test webhook dispatched."
  }
}

The test payload is:

{
  "event": "webhook.test",
  "timestamp": "2026-02-25T12:00:00+00:00",
  "data": {
    "message": "This is a test webhook delivery from YorAuth."
  }
}

Error Responses