Endpoints
Webhooks
API reference for registering and managing incoming webhooks.
Overview
Webhooks allow external services to push events to Docimal in real time. Register webhook endpoints, map events to workflow triggers, and receive data from third-party services with built-in HMAC-SHA256 signature verification for security.
Register Webhook
POST /webhooks/register — Create a new webhook endpoint. Body: { name: string, events: string[], targetTriggerId?: string }. Returns: { webhookUrl: string, secret: string }. The webhookUrl is the URL external services should send events to. The secret is used for HMAC-SHA256 signature verification — store it securely.
List Webhooks
GET /webhooks — List all registered webhooks. Filter by workspace. Each webhook includes: name, URL, event mapping, active status, and creation date.
Receiving Webhooks
POST /webhooks/incoming/{path} — Public endpoint that receives incoming webhook payloads. Docimal verifies the HMAC-SHA256 signature in the X-Webhook-Signature header using the webhook secret. Valid payloads are routed to the configured workflow trigger in the automation service.
Webhook Security
All incoming webhooks are verified using HMAC-SHA256 signatures. The sending service must compute the signature using the shared secret and include it in the X-Webhook-Signature header. Requests with missing or invalid signatures are rejected with HTTP 401. Webhook secrets are encrypted at rest using AES-256-GCM.
Delete Webhook
DELETE /webhooks/{id} — Remove a webhook registration. The webhook URL immediately stops accepting events. Any pending deliveries from external services will receive HTTP 404.