WEBHOOK-API.md

Webhook API Documentation

Overview

The DEAF-FIRST Platform webhook system allows you to register and manage webhooks to receive real-time notifications about events in the platform. This replaces the functionality that was previously handled by Xano.

Base URL

http://localhost:3000/api

Webhook Management Endpoints

1. List All Webhooks

Get a list of all registered webhooks.

Endpoint: GET /webhooks

Response:

{
  "success": true,
  "count": 2,
  "webhooks": [
    {
      "id": "wh_1234567890_abc123",
      "name": "Production Webhook",
      "url": "https://example.com/webhook",
      "events": ["user.created", "user.updated"],
      "secret": "***",
      "active": true,
      "createdAt": "2025-12-05T07:00:00.000Z",
      "updatedAt": "2025-12-05T07:00:00.000Z"
    }
  ]
}

2. Get Specific Webhook

Retrieve details of a specific webhook by ID.

Endpoint: GET /webhooks/:id

Response:

{
  "success": true,
  "webhook": {
    "id": "wh_1234567890_abc123",
    "name": "Production Webhook",
    "url": "https://example.com/webhook",
    "events": ["user.created"],
    "secret": "***",
    "active": true,
    "createdAt": "2025-12-05T07:00:00.000Z",
    "updatedAt": "2025-12-05T07:00:00.000Z"
  }
}

3. Register New Webhook

Create a new webhook registration.

Endpoint: POST /webhooks

Request Body:

{
  "name": "My Webhook",
  "url": "https://example.com/webhook",
  "events": ["user.created", "user.updated"],
  "secret": "optional-custom-secret"
}

Response:

{
  "success": true,
  "message": "Webhook registered successfully",
  "webhook": {
    "id": "wh_1234567890_abc123",
    "name": "My Webhook",
    "url": "https://example.com/webhook",
    "events": ["user.created", "user.updated"],
    "secret": "generated-or-custom-secret",
    "active": true,
    "createdAt": "2025-12-05T07:00:00.000Z",
    "updatedAt": "2025-12-05T07:00:00.000Z"
  }
}

4. Update Webhook

Update an existing webhook.

Endpoint: PUT /webhooks/:id

Request Body:

{
  "name": "Updated Webhook Name",
  "url": "https://new-url.com/webhook",
  "events": ["user.created", "user.deleted"],
  "active": false
}

Response:

{
  "success": true,
  "message": "Webhook updated successfully",
  "webhook": {
    "id": "wh_1234567890_abc123",
    "name": "Updated Webhook Name",
    "url": "https://new-url.com/webhook",
    "events": ["user.created", "user.deleted"],
    "secret": "***",
    "active": false,
    "createdAt": "2025-12-05T07:00:00.000Z",
    "updatedAt": "2025-12-05T08:00:00.000Z"
  }
}

5. Delete Webhook

Delete a webhook registration.

Endpoint: DELETE /webhooks/:id

Response:

{
  "success": true,
  "message": "Webhook deleted successfully"
}

6. Get Delivery History

View delivery history for a specific webhook.

Endpoint: GET /webhooks/:id/deliveries

Response:

{
  "success": true,
  "count": 5,
  "deliveries": [
    {
      "id": "del_1234567890_xyz789",
      "webhookId": "wh_1234567890_abc123",
      "event": "user.created",
      "payload": {
        "event": "user.created",
        "timestamp": "2025-12-05T07:00:00.000Z",
        "data": { "userId": "123", "email": "user@example.com" }
      },
      "response": {
        "status": 200,
        "body": "OK"
      },
      "attempts": 1,
      "status": "success",
      "timestamp": "2025-12-05T07:00:00.000Z"
    }
  ]
}

7. List Available Event Types

Get a list of all available webhook event types.

Endpoint: GET /webhooks/events/types

Response:

{
  "success": true,
  "count": 12,
  "events": [
    "user.created",
    "user.updated",
    "user.deleted",
    "auth.login",
    "auth.logout",
    "document.uploaded",
    "document.processed",
    "accessibility.request",
    "sync.started",
    "sync.completed",
    "ai.process.started",
    "ai.process.completed"
  ]
}

8. Trigger Webhook Event (Testing)

Manually trigger a webhook event for testing purposes.

Endpoint: POST /webhooks/trigger

Request Body:

{
  "event": "user.created",
  "data": {
    "userId": "123",
    "email": "test@example.com",
    "name": "Test User"
  }
}

Response:

{
  "success": true,
  "message": "Webhook event triggered successfully"
}

Incoming Webhook Endpoints

These endpoints receive webhooks from external services like Xano.

Receive External Webhook

Endpoint: POST /incoming-webhooks/:service

Where :service can be:

• xano - For Xano webhooks
• stripe - For Stripe webhooks
• custom - For custom webhooks

Headers:

• X-Webhook-Signature: HMAC signature for verification
• X-Webhook-Event: Event type

Request Body: (varies by service)

{
  "event": "record.created",
  "data": {
    "id": "123",
    "table": "users",
    "record": { "name": "John Doe" }
  }
}

Response:

{
  "success": true,
  "message": "Webhook received successfully",
  "eventId": "evt_1234567890_xyz789"
}

Health Check

Endpoint: GET /incoming-webhooks/health

Response:

{
  "success": true,
  "message": "Incoming webhook endpoint is healthy",
  "timestamp": "2025-12-05T07:00:00.000Z"
}

Webhook Security

Signature Verification

All outgoing webhooks include an X-Webhook-Signature header containing an HMAC-SHA256 signature of the payload.

To verify a webhook:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Headers

Every webhook delivery includes these headers:

• Content-Type: application/json
• X-Webhook-Signature: HMAC signature for verification
• X-Webhook-Event: The event type (e.g., "user.created")
• X-Webhook-Delivery: Unique delivery ID

Event Types

User Events

• user.created - Triggered when a new user is created
• user.updated - Triggered when user information is updated
• user.deleted - Triggered when a user is deleted

Authentication Events

• auth.login - Triggered when a user logs in
• auth.logout - Triggered when a user logs out

Document Events

• document.uploaded - Triggered when a document is uploaded
• document.processed - Triggered when document processing completes

Accessibility Events

• accessibility.request - Triggered when accessibility features are requested

Sync Events

• sync.started - Triggered when synchronization begins
• sync.completed - Triggered when synchronization completes

AI Events

• ai.process.started - Triggered when AI processing begins
• ai.process.completed - Triggered when AI processing completes

Example Webhook Payload

{
  "event": "user.created",
  "timestamp": "2025-12-05T07:00:00.000Z",
  "data": {
    "userId": "usr_1234567890",
    "email": "user@example.com",
    "name": "John Doe",
    "preferences": {
      "signLanguage": true,
      "visualAccessibility": true
    }
  }
}

Migrating from Xano

If you were previously using Xano webhooks:

1. Register your webhook endpoints using the POST /webhooks endpoint
2. Configure incoming webhooks to receive events from Xano at /incoming-webhooks/xano
3. Update your Xano configuration to point to your new webhook URL
4. Test webhook delivery using the trigger endpoint

Error Handling

All endpoints return consistent error responses:

{
  "success": false,
  "error": "Error type",
  "message": "Detailed error message"
}

Common HTTP status codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 404 - Not Found
• 500 - Internal Server Error

Rate Limiting

Currently, there are no rate limits applied to webhook endpoints. In production, consider implementing rate limiting based on your needs.

Best Practices

1. Verify signatures - Always verify webhook signatures to ensure authenticity
2. Handle idempotency - Webhook events may be delivered multiple times; handle duplicates gracefully
3. Respond quickly - Return a 200 response as soon as possible; process webhooks asynchronously
4. Log deliveries - Use the delivery history endpoint to monitor webhook health
5. Use HTTPS - Always use HTTPS URLs for webhook endpoints in production
6. Rotate secrets - Periodically rotate webhook secrets for security

Support

For issues or questions about the webhook system, please refer to the main documentation or create an issue in the repository.