Webhooks API

Configure webhooks to receive real-time event notifications when things happen in your application. YorAuth sends an HTTP POST to your endpoint when subscribed events occur.

Authentication

All endpoints require a valid JWT access token with the webhooks:manage permission:

Authorization: Bearer {access_token}

Supported Events

Webhook Signatures

Each webhook delivery includes a signature header so you can verify the payload came from YorAuth:

X-YorAuth-Signature: sha256=abc123...
X-YorAuth-Event: user.created
X-YorAuth-Delivery-Id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
X-YorAuth-Timestamp: 1708864800

To verify: compute sha256 HMAC of the raw JSON payload body using your webhook secret. The result should match the value after sha256= in the signature header.

const crypto = require('crypto');
const sig = crypto
  .createHmac('sha256', webhookSecret)
  .update(rawBody)
  .digest('hex');

const isValid = sig === receivedSignature.replace('sha256=', '');

Retry Policy

Failed deliveries are retried 3 times with exponential backoff: 30 seconds, 5 minutes, 30 minutes. A delivery is considered failed if your endpoint returns a non-2xx status or does not respond within 30 seconds.

List Webhooks

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

List all webhook configurations for the application.

Response

200 OK

{
  "data": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "url": "https://example.com/webhooks/yorauth",
      "events": ["user.created", "user.login"],
      "is_active": true,
      "created_at": "2026-02-25T12:00:00Z",
      "updated_at": "2026-02-25T12:00:00Z"
    }
  ]
}

Create Webhook

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

Create a new webhook configuration. The signing secret is returned only on creation and cannot be retrieved afterwards.

Request Body

Response

201 Created

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "url": "https://example.com/webhooks/yorauth",
    "secret": "wh_live_abc123...",
    "events": ["user.created", "user.login"],
    "is_active": true,
    "created_at": "2026-02-25T12:00:00Z"
  }
}

The response is sent with Cache-Control: no-store to prevent proxy caching of the secret.

Error Responses

Get Webhook

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

Retrieve a single webhook configuration. The secret is not included in this response.

Response

200 OK

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "url": "https://example.com/webhooks/yorauth",
    "events": ["user.created", "user.login"],
    "is_active": true,
    "created_at": "2026-02-25T12:00:00Z",
    "updated_at": "2026-02-25T12:00:00Z"
  }
}

Error Responses

Update Webhook

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

Update a webhook's URL, subscribed events, or active status. All fields are optional.

Request Body

Response

200 OK

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "url": "https://example.com/webhooks/yorauth-v2",
    "events": ["user.created", "user.deleted"],
    "is_active": true,
    "created_at": "2026-02-25T12:00:00Z",
    "updated_at": "2026-02-25T14:00:00Z"
  }
}

Error Responses

Delete Webhook

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

Delete a webhook configuration. Pending deliveries will not be retried.

Response

204 No Content

Error Responses

List Deliveries

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

List the 50 most recent delivery attempts for a webhook, ordered by most recent first.

Response

200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "event": "user.created",
      "response_status": 200,
      "delivered_at": "2026-02-25T12:00:05Z",
      "retry_count": 0,
      "created_at": "2026-02-25T12:00:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "event": "user.login",
      "response_status": 500,
      "delivered_at": null,
      "retry_count": 3,
      "created_at": "2026-02-25T11:00:00Z"
    }
  ]
}

Error Responses