deaf-first-platform

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:

Register your webhook endpoints using the POST /webhooks endpoint
Configure incoming webhooks to receive events from Xano at /incoming-webhooks/xano
Update your Xano configuration to point to your new webhook URL
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

Verify signatures - Always verify webhook signatures to ensure authenticity
Handle idempotency - Webhook events may be delivered multiple times; handle duplicates gracefully
Respond quickly - Return a 200 response as soon as possible; process webhooks asynchronously
Log deliveries - Use the delivery history endpoint to monitor webhook health
Use HTTPS - Always use HTTPS URLs for webhook endpoints in production
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.

This site is open source. Improve this page.