Webhook System Documentation

Overview

Ledoc webhooks let you receive near real-time HTTP notifications whenever events occur inside the system (e.g., an item is created, updated, archived, etc.). When a matching event fires, Ledoc sends an HTTP POST request to your registered URL with a JSON body describing the event.

Required role: All webhook management endpoints require the caller to be a Primary Admin.

Endpoints

1. Register a Webhook

POST /v1/webhooks

Register a new webhook to receive event notifications for a specific module.

Request body

Constraints

• The URL must use the https scheme.
• The combination of (module, url) must be unique per customer — you cannot register the same URL for the same module twice.

Response 200 OK — returns the created WebhookRegistration object.

2. List All Webhooks

GET /v1/webhooks

Returns all webhook registrations for the current authenticated customer.

Response 200 OK — returns an array of WebhookRegistration objects.

3. Get a Webhook

GET /v1/webhooks/{webhook_id}

Returns a single webhook registration by its ID.

Path parameters

Response 200 OK — returns a single WebhookRegistration object.

Error responses

• 404 Not Found — webhook does not exist.

4. Update a Webhook

PATCH /v1/webhooks/{webhook_id}

Partially updates an existing webhook registration. All fields are optional — only the fields you provide will be changed.

Path parameters

Request body (all fields optional)

Response 200 OK — returns the updated WebhookRegistration object.

Error responses

• 400 Bad Request — validation failure (invalid URL, empty event_types, etc.).
• 404 Not Found — webhook does not exist.
• 409 Conflict — the new (module, url) combination already exists for this customer.

5. Delete a Webhook

DELETE /v1/webhooks/{webhook_id}

Permanently deletes a webhook registration. All associated delivery history is also removed (cascade).

Path parameters

Response 204 No Content

Error responses

• 404 Not Found — webhook does not exist.

6. Send a Test Event

POST /v1/webhooks/events/send_test

Manually publishes a test event that triggers delivery to any matching registered webhooks. Useful for validating your endpoint is working correctly before relying on real events.

Request body

Response 200 OK

{
  "message_id": "<SQS message ID or fallback ID>"
}

The test event is published to the same delivery pipeline as real events. Any registered webhook whose module and event_types match the request will receive a delivery.

WebhookRegistration Object

This is the object returned by all webhook management endpoints.

Note: The secret_key field is never included in API responses for security reasons.

Modules

The following module values are accepted for the module field:

Event Types

The following values are accepted for the event_types / event_type fields:

Supported Events by API

The tables below list every API endpoint that publishes a webhook event, grouped by module.

Equipment

Employee

Document

Supplier

Task

Location

Team

Category

Review Group

Review Template

Other

Receiving Webhook Deliveries

When a subscribed event occurs, Ledoc sends an HTTP POST request to your registered URL with the following characteristics:

Request Headers

Request Body

The body is a JSON object containing the event data for the affected item. The exact structure depends on the module and event type. If you configured included_fields, only the whitelisted fields will be present.

Example — CLONE event payload:

{
  "cloned_from": 123,
  "cloned_to": 456
}

Example — REVIEW event payload:

{
  "overall_status": "PASS"
}

Example — DELETE, ARCHIVE, UNARCHIVE event payload:

{}

Expected Response

Your endpoint should return any 2xx HTTP status code to indicate successful receipt. If a non-2xx status is returned, or if the request times out (60-second timeout), the delivery is marked as failed and will be retried.

Verifying Signatures

If you configure a secret_key on a webhook, every delivery will include an X-Webhook-Signature header. This allows you to verify that the request genuinely came from Ledoc and that the payload has not been tampered with.

Algorithm: HMAC-SHA256

How to verify (pseudocode):

expected_signature = HMAC-SHA256(secret_key, JSON.stringify(request_body))
if hex(expected_signature) == request.headers["X-Webhook-Signature"]:
    # Payload is authentic

Field Filtering (included_fields)

By default, webhooks deliver the full event payload. You can limit the fields sent using included_fields — only top-level JSON keys that appear in this list will be included in the delivery.

Example: If included_fields is ["id", "name", "status"], the delivered payload will only contain those three fields even if the full item has many more.

If included_fields is null or an empty array, the complete payload is delivered.

Retry Behavior

If delivery fails (non-2xx response or network error), Ledoc will retry up to 3 times using exponential backoff:

After 3 failed retries the delivery is marked as EXHAUSTED and no further attempts are made.

Delivery Statuses

Disabling a Webhook

Instead of deleting a webhook, you can temporarily disable it by setting is_active to false via the Update endpoint. Disabled webhooks will not receive any deliveries until re-enabled.