Webhooks API

Receive real-time notifications for events in your application via webhooks.

Overview

Webhooks allow your application to receive real-time HTTP notifications when events occur. Configure webhook endpoints to listen for events like user registration, subscription changes, and more.

💡 Tip: All webhook requests include a signature header for verification to ensure requests are from AuthCore.

List Webhooks

GET/api/webhooks

List all configured webhooks. Requires admin role.

Response (200 OK)

json

Create Webhook

POST/api/webhooks

Register a new webhook endpoint. Requires admin role.

Request Body

json

Response (201 Created)

json

⚠️ Important: Save the webhook secret securely. You'll need it to verify webhook signatures.

Update Webhook

PATCH/api/webhooks/:webhookId

Update webhook configuration. Requires admin role.

Request Body

json

Response (200 OK)

json

Delete Webhook

DELETE/api/webhooks/:webhookId

Remove webhook endpoint. Requires admin role.

Response (200 OK)

json

Event Types

Available webhook event types:

User Events

  • user.created - New user registered
  • user.updated - User profile updated
  • user.deleted - User account deleted
  • user.email_verified - Email verified

Organization Events

  • organization.created - New organization created
  • organization.updated - Organization updated
  • organization.deleted - Organization deleted
  • organization.member_added - Member joined
  • organization.member_removed - Member left

Subscription Events

  • subscription.created - New subscription
  • subscription.updated - Subscription changed
  • subscription.canceled - Subscription canceled
  • subscription.renewed - Subscription renewed

Security Events

  • security.account_locked - Account locked
  • security.suspicious_login - Suspicious activity
  • security.2fa_enabled - 2FA enabled
  • security.2fa_disabled - 2FA disabled

Webhook Payload

All webhooks are sent as POST requests with this structure:

Example Webhook Payload

Signature Verification

Verify webhook authenticity using the X-Webhook-Signature header:

Signature Verification (Node.js)

Best Practices

✅ Always Verify Signatures

Never trust webhook data without verifying the signature

⚡ Return 200 Quickly

Process webhooks asynchronously and return success immediately

🔄 Handle Idempotency

Use event IDs to prevent processing the same event twice

🔐 Use HTTPS

Webhook URLs must use HTTPS in production

Get Webhook Deliveries

GET/api/webhooks/:webhookId/deliveries

View webhook delivery history and status. Requires admin role.

Response (200 OK)

json

Retry Failed Delivery

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

Manually retry a failed webhook delivery. Requires admin role.

Response (200 OK)

json

Related

Billing API →

Subscribe to billing events

Node.js SDK →

Handle webhooks in Node.js