Skip to content

WEBHOOK-API.md

Latest commit

 

History

History
403 lines (321 loc) · 8.95 KB

WEBHOOK-API.md

File metadata and controls

403 lines (321 loc) · 8.95 KB
Raw

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.