Webhooks

Receive real-time HTTP notifications when auth events happen in your organization. Register an HTTPS endpoint and AuthWorx will POST a signed payload whenever a member joins, a user logs in, and more.

How it works

When an event occurs (e.g. member.joined), AuthWorx sends an HTTP POST to every active webhook URL registered for that event in your org. Payloads are signed with HMAC-SHA256 using a secret you set at creation time — see Signature Verification.

If your endpoint does not respond with a 2xx status within 10 seconds, the delivery is retried automatically.

Retry schedule

Attempt	Delay after previous failure
1 (initial)	Immediate
2	1 minute
3	5 minutes
4 (final)	30 minutes

After 4 attempts the delivery is marked failed permanently. Delivery logs are retained for 30 days.

For slow operations (sending emails, provisioning infrastructure), enqueue a background job rather than doing the work inline. Your handler must respond within 10 seconds.

Create a webhook subscription

POST /org/webhooks

Request body

Field	Type		Description
url	string	required	HTTPS endpoint that will receive the POST. Must be publicly reachable.
events	string[]	required	Array of event names to subscribe to. See Event Catalog.
description	string	optional	Human-readable label for this subscription.

Request

{
  "url": "https://app.acme.com/webhooks/authworx",
  "events": ["member.invited", "member.joined", "member.removed"],
  "description": "Sync org membership to our database"
}

Response (201)

{
  "status": "success",
  "data": {
    "secret": "whs_a1b2c3d4e5f6...",
    "webhook": {
      "id": "wh_01ABCD",
      "url": "https://app.acme.com/webhooks/authworx",
      "events": ["member.invited", "member.joined", "member.removed"],
      "description": "Sync org membership to our database",
      "isActive": true,
      "createdAt": "2025-05-23T12:00:00.000Z"
    }
  }
}

Copy the secret now — it is shown once. Store it as AUTHWORX_WEBHOOK_SECRET in your environment. Use it to verify incoming payloads — see Signature Verification.

List webhooks

GET /org/webhooks

Response (200)

{
  "status": "success",
  "data": {
    "webhooks": [
      {
        "id": "wh_01ABCD",
        "url": "https://app.acme.com/webhooks/authworx",
        "events": ["member.invited", "member.joined"],
        "isActive": true,
        "createdAt": "2025-05-23T12:00:00.000Z"
      }
    ]
  }
}

Update a webhook

PATCH /org/webhooks/:id

Request body (all fields optional)

Field	Type	Description
url	string	New endpoint URL.
events	string[]	Replace the full events list.
isActive	boolean	Set `false` to pause deliveries without deleting the subscription.
description	string	Update the label.

Delete a webhook

DELETE /org/webhooks/:id

Response (200)

{ "status": "success", "data": { "message": "Webhook deleted" } }

Send a test ping

Sends a webhook.test event to the subscription's URL immediately. Useful for verifying your endpoint and signature verification logic.

POST /org/webhooks/:id/test

Response (200)

{ "status": "success", "data": { "deliveryId": "del_01WXYZ" } }

Delivery history

Returns the last 50 deliveries for a webhook, newest first.

GET /org/webhooks/:id/deliveries

Response (200)

{
  "status": "success",
  "data": {
    "deliveries": [
      {
        "id": "del_01WXYZ",
        "event": "member.joined",
        "status": "success",
        "httpStatus": 200,
        "attempts": 1,
        "createdAt": "2025-05-23T14:00:00.000Z"
      },
      {
        "id": "del_01WABC",
        "event": "member.invited",
        "status": "failed",
        "httpStatus": 503,
        "attempts": 4,
        "lastError": "Endpoint returned 503",
        "createdAt": "2025-05-23T13:00:00.000Z"
      }
    ]
  }
}

Delivery statuses

Status	Description
`pending`	Queued, not yet attempted.
`success`	Endpoint returned 2xx.
`retrying`	Failed, scheduled for retry.
`failed`	All attempts exhausted.

Use webhook.site during development to inspect raw deliveries without running a local server.