Skip to main content

​
Webhooks

Webhooks are the recommended way to receive asynchronous notifications about Business API operations. They are driven by the task system and delivered by the WebhookService with retry and detailed audit logging.

​
Webhook lifecycle

The webhook flow is:
  1. Trigger event – a file task or main task transitions state.
  2. Prepare payload – the system builds a JSON payload and HMAC signature headers.
  3. Send to client – an HTTP request is made to your registered webhook_url.
  4. Log to audit table – each attempt is recorded with status, payload, response, and error.
  5. Retry (optional) – failed deliveries are retried until the configured limit is reached.
All deliveries are logged in the WEBHOOK_AUDIT_LOGS table, including status, attempt number, response status, and any error message.

​
Registering webhooks

Webhooks can be registered or managed in two ways:
  • Via POST /v1/developer/generate-api-key by passing a webhook_url (and optional webhook_secret).
  • Via dedicated developer webhook endpoints:
    • POST /v1/developer/webhooks
    • GET /v1/developer/webhooks
    • DELETE /v1/developer/webhook/:webhookId
    • GET /v1/developer/webhooks/audit
All /v1/developer/* routes require authenticated user JWTs (not API keys).

​
Events

From the Business API design, the main events are:
  • operation.completed – main task finished (all file tasks completed or partially completed).
  • operation.failed – main task failed (all file tasks failed).
  • fileTask.completed – individual file task completed.
  • fileTask.failed – individual file task failed.

​
operation.completed / partially completed

{
  "type": "operation.completed",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "payload": {
    "main_task": {
      "id": "aaa...",
      "status": "completed",
      "count": {
        "total": 2,
        "success": 2,
        "failed": 0
      },
      "file_data": [
        {
          "file_key": "bbb...",
          "status": "completed",
          "download_link": "xz..."
        },
        {
          "file_key": "ccc...",
          "status": "failed",
          "error": "Internal Server error/invalid input file"
        }
      ]
    }
  }
}

​
fileTask.completed

{
  "type": "fileTask.completed",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "data": {
    "file_key": "aaa...",
    "status": "completed"
  }
}

​
fileTask.failed

{
  "type": "fileTask.failed",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "data": {
    "file_key": "aaa...",
    "status": "failed",
    "error": "..."
  }
}

​
Delivery & retries

The webhook audit and retry flow (simplified from the design docs):
  • On each attempt, a row is inserted into WEBHOOK_AUDIT_LOGS with:
    • event_type
    • target_url
    • payload
    • response_status
    • attempt_number
    • status (success / failed)
    • error_message
    • sent_at
  • If retries are enabled, failed attempts are rescheduled until either:
    • A retry succeeds.
    • The max retry count is reached.
You can inspect delivery health and failures via GET /v1/developer/webhooks/audit.

​
Security

When a webhook_secret is configured, webhooks are signed with an HMAC (exact header and algorithm are implementation details, typically X-D3-Signature with an HMAC‑SHA256 over the request body). Recommended best practices:
  • Always validate signatures using the shared webhook_secret.
  • Use HTTPS for webhook endpoints.
  • Treat webhook bodies as event notifications and fetch sensitive data via the Business API where needed.