Webhooks

Our system will send webhooks to notify your server of various events. When one of these events occurs, a POST request is made to the provided webhook URL with a JSON payload describing the event.

Webhook Concepts

Event Types

The following event types are available:

• wallet.created: Triggered when a new wallet is created
• webhook.created: Triggered when a new webhook is configured
• webhook.updated: Triggered when a webhook configuration is modified
• webhook.tested: Triggered when a webhook test is performed
• webhook.secret.rolled: Triggered when a webhook signing secret is rotated
• hcs.topic.created: Triggered when a new HCS topic is created
• hcs.message.added: Triggered when a message is added to an HCS topic
• ai.processed: Triggered when AI processing completes
• ai.promptTested: Triggered when an AI prompt is tested
• ocr.started: Triggered when OCR processing begins
• ocr.completed: Triggered when OCR processing finishes

Webhook Properties

A webhook configuration includes:

Field	Type	Description
webhookId	string	Unique identifier for the webhook
name	string	Name of the webhook
description	string	Description of the webhook
url	string	The URL where webhooks will be sent
enabledEvents	string[]	List of event names this webhook listens to
signingSecret	string	Secret used to sign the webhook payload
status	string	Status of webhook: ‘active’, ‘paused’, or ‘disabled’
lastTriggeredAt	string	ISO timestamp of last webhook trigger
createdAt	string	ISO timestamp of webhook creation

Webhook Management

Creating a Webhook

To create a new webhook, send a POST request with the webhook configuration:

POST /webhooks
{
  "name": "Document Processing Webhook",
  "description": "Receives notifications for document processing events",
  "url": "https://api.example.com/webhooks",
  "enabledEvents": ["webhook.created", "ocr.completed", "api.processed"]
}

Response:

{
  "webhookId": "18ab50c1-070d-441f-a77c-3fcaaffe738d",
  "name": "Document Processing Webhook",
  "description": "Receives notifications for document processing events",
  "url": "https://api.example.com/webhooks",
  "enabledEvents": ["webhook.created", "ocr.completed", "api.processed"],
  "status": "active",
  "createdAt": "2024-03-20T10:30:00Z"
}

Retrieving Webhooks

List All Webhooks

GET /webhooks?page=0&limit=10

Response:
{
  "total": 25,
  "page": 0,
  "perPage": 10,
  "hasNext": true,
  "hasPrev": false,
  "items": [
    {
      "webhookId": "18ab50c1-070d-441f-a77c-3fcaaffe738d",
      "name": "Document Processing Webhook",
      "url": "https://api.example.com/webhooks",
      "enabledEvents": ["webhook.created", "ocr.completed", "api.processed"],
      "status": "active",
      "lastTriggeredAt": "2024-03-20T10:35:00Z",
      "createdAt": "2024-03-20T10:30:00Z"
    }
  ]
}

Get Single Webhook

GET /webhooks/18ab50c1-070d-441f-a77c-3fcaaffe738d

Response:
{
  "webhookId": "18ab50c1-070d-441f-a77c-3fcaaffe738d",
  "name": "Document Processing Webhook",
  "description": "Receives notifications for document processing events",
  "url": "https://api.example.com/webhooks",
  "enabledEvents": ["webhook.created", "ocr.completed", "api.processed"],
  "status": "active",
  "lastTriggeredAt": "2024-03-20T10:35:00Z",
  "createdAt": "2024-03-20T10:30:00Z"
}

Webhook Security

Each webhook has a signing secret used to verify request authenticity. You can:

Get Signing Secret

GET /webhooks/18ab50c1-070d-441f-a77c-3fcaaffe738d/signing-secret

Response:
{
  "secret": "whsec_abcdef123456789"
}

Roll (Rotate) Signing Secret

POST /webhooks/roll-secret/18ab50c1-070d-441f-a77c-3fcaaffe738d

Response:
{
  "webhookId": "18ab50c1-070d-441f-a77c-3fcaaffe738d",
  "signingSecret": "whsec_newSecret987654321"
}

Testing Webhooks

Send a test event to verify your webhook configuration:

POST /webhooks/test/18ab50c1-070d-441f-a77c-3fcaaffe738d

Response:
{
  "success": true,
  "message": "Test webhook sent successfully"
}

Webhook Request History

View the history of webhook deliveries:

GET /webhooks/18ab50c1-070d-441f-a77c-3fcaaffe738d/requests?page=0&limit=10

Response:
{
  "total": 50,
  "page": 0,
  "perPage": 10,
  "hasNext": true,
  "hasPrev": false,
  "items": [
    {
      "notificationId": "ffb7b1ae-807f-4f5d-92dc-578229012977",
      "content": {
        "eventType": "event.uploadedDocument",
        "timestamp": 1696732952771
      },
      "externalEventType": "event.uploadedDocument",
      "createdAt": "2024-03-20T10:35:00Z"
    }
  ]
}

API Endpoints

Method	Endpoint	Description
GET	/webhooks	List all webhooks
POST	/webhooks	Create a new webhook
GET	/webhooks/:webhookId	Get a specific webhook
PUT	/webhooks/:webhookId	Update a webhook
DELETE	/webhooks/:webhookId	Delete a webhook
POST	/webhooks/test/:webhookId	Test a webhook
POST	/webhooks/roll-secret/:webhookId	Roll the webhook signing secret
GET	/webhooks/:webhookId/requests	Get webhook request history
GET	/webhooks/:webhookId/signing-secret	Get the webhook signing secret

Pagination

List endpoints support pagination with the following query parameters:

• page: Page number (default: 0)
• limit: Items per page (default: 10)

Best Practices

1. Security:

   • Store your webhook signing secret securely
   • Always verify webhook signatures before processing
   • Regularly rotate your signing secret using the roll secret endpoint

2. Reliability:

   • Implement proper error handling for webhook receipts
   • Return 200 status codes promptly to acknowledge receipt
   • Process webhook data asynchronously after acknowledging

3. Monitoring:

   • Regularly check webhook request history for failed deliveries
   • Monitor webhook status and last triggered time
   • Set up alerts for webhook failures

Webhook Payload

When an event occurs, your webhook endpoint will receive a POST request with a payload with a structure based on the following example:

{
  "id": "ffb7b1ae-807f-4f5d-92dc-578229012977",
  "type": "ocr.completed",
  "data": {
    object: {
      "timestamp": 1696732952771,
      "some-data": "some value"
    },
  }
}