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:**
```json

{

  "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:**
```json

{

  "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:**
```json

{

  "name": "My Webhook",

  "url": "https://example.com/webhook",

  "events": ["user.created", "user.updated"],

  "secret": "optional-custom-secret"

}

```

**Response:**
```json

{

  "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:**
```json

{

  "name": "Updated Webhook Name",

  "url": "https://new-url.com/webhook",

  "events": ["user.created", "user.deleted"],

  "active": false

}

```

**Response:**
```json

{

  "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:**
```json

{

  "success": true,

  "message": "Webhook deleted successfully"

}

```

### 6. Get Delivery History

View delivery history for a specific webhook.

**Endpoint:** `GET /webhooks/:id/deliveries`

**Response:**
```json

{

  "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:**
```json

{

  "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:**
```json

{

  "event": "user.created",

  "data": {

    "userId": "123",

    "email": "test@example.com",

    "name": "Test User"

  }

}

```

**Response:**
```json

{

  "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)
```json

{

  "event": "record.created",

  "data": {

    "id": "123",

    "table": "users",

    "record": { "name": "John Doe" }

  }

}

```

**Response:**
```json

{

  "success": true,

  "message": "Webhook received successfully",

  "eventId": "evt_1234567890_xyz789"

}

```

### Health Check

**Endpoint:** `GET /incoming-webhooks/health`

**Response:**
```json

{

  "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:

```javascript

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

```json

{

  "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:

```json

{

  "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.