Webhooks

Webhooks let your application receive real-time HTTP notifications when events happen in YorAuth, so you can react immediately instead of polling the API.

How Webhooks Work

When an event occurs — a user registers, a role is assigned, MFA is enabled — YorAuth creates a delivery record and dispatches an HTTP POST request to your registered endpoint. The request body is a JSON payload describing the event. Your endpoint must respond with a 2xx status code within 30 seconds.

Each outgoing request is signed with an HMAC-SHA256 signature so you can verify the payload originated from YorAuth and has not been tampered with.

In This Section

Page	Description
Setup	Create and manage webhook endpoints via the API
Events	Complete list of event types and their payloads
Security	Verify signatures and prevent replay attacks
Delivery & Retry	Retry schedule, auto-disable behavior, and delivery logs

Quick Example

bash

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"]
  }'

The response includes a secret you must store securely. Use it to verify every incoming request.

When a matching event fires, YorAuth sends a POST to your URL:

json

{
  "event": "user.created",
  "timestamp": "2026-02-25T12:00:00+00:00",
  "data": {
    "user_id": "usr_01hnxyz",
    "email": "jane@example.com",
    "name": "Jane Smith"
  }
}

The secret is only returned once — at creation time and after a secret rotation. Store it immediately in a secure location such as an environment variable or secrets manager.