Skip to main content
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 are registered and managed through the D3 dashboard:
  1. Sign in to your account at dragdropdo.com/auth/signin
  2. Navigate to your Account section
  3. Go to the Register Webhook section
  4. Enter your webhook URL and optional webhook secret
  5. Save your webhook configuration
You can also configure webhooks when generating an API key in the dashboard by providing a webhook URL during the API key creation process.

​
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 through the webhook management section in your account dashboard.

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