Webhooks

Overview

When you create an asynchronous document request, DocLift generates the documents in the background and delivers the results to your application via a webhook. This avoids having to poll the API for status updates.

---

Configuration

To receive webhooks, configure a Webhook URL on your external application from the DocLift dashboard. Navigate to your API key settings and fill in the "Webhook URL" field with the endpoint on your server that will receive the notifications.

The webhook URL must be a valid HTTPS endpoint that is publicly accessible. An asynchronous document request will be rejected if no webhook URL is configured on the external application.

---

Payload format

When all document generations in a request are completed, DocLift sends a POST request to your webhook URL with the document request data as JSON body:

{
    "id": 100004,
    "tag": "Batch#12",
    "type": "asynchrone",
    "timestamp": "2024-01-15T10:35:00+01:00",
    "documents_generations": [
        {
            "id": 100230,
            "tag": "Subscription#102",
            "generated_at": "2021-03-14 16:55:14 +0100",
            "created_at": "2021-03-14 16:55:13 +0100",
            "generation_status": "success",
            "file": {
                "filename": "Contract-1615737313.pdf",
                "url": "https://doclift.s3.eu-west-3.amazonaws.com/d207f8fe.pdf?[...]",
                "size": 40290
            }
        }
    ]
}

The S3 URLs in webhook payloads expire after 2 hours.

---

Signature verification

Every webhook request includes a X-Doclift-Signature header containing an HMAC-SHA256 signature of the request body, signed with your API key (secret key) as the secret. The signature is prefixed with sha256=.

To verify the authenticity of a webhook:

1. Read the raw request body
2. Compute the HMAC-SHA256 of the body using your API key as the secret
3. Compare the computed signature with the value in the X-Doclift-Signature header

Example in Ruby:

computed = "sha256=" + OpenSSL::HMAC.hexdigest(
  "SHA256",
  api_secret_key,
  request.raw_post
)
if computed == request.headers["X-Doclift-Signature"]
  # Signature is valid
end

---

Response expectations

DocLift expects your webhook endpoint to respond with an HTTP 2xx status code within 3 seconds. Any other status code or a timeout is treated as a failure.

---

Retry policy

If a webhook delivery fails (non-2xx response or timeout), DocLift will retry with exponential backoff using the formula:

delay = min(30 × 2^(n-1), 1800) seconds

Where n is the retry attempt number:

• 1st retry: 30 seconds
• 2nd retry: 60 seconds
• 3rd retry: 120 seconds
• 4th retry: 240 seconds
• ...capped at 30 minutes maximum

The maximum number of retry attempts defaults to 3 and is configurable per account (see webhooks_replays_count in the User info endpoint).

If all retries are exhausted, the webhook is marked as failed. You can still retrieve the document request data via the GET endpoint.