6. Webhooks

Webhooks allow your system to receive real-time updates about the e-sign process.

Instead of polling for updates, DocEndorse will send HTTP POST requests to your configured webhook URL whenever important signing events occur.

Why Use Webhooks?

Webhooks allow you to:

• Track document status changes
• Update your internal systems automatically
• Notify users when signing is complete
• Maintain real-time synchronization

Configuring a Webhook

From your developer dashboard:

1. Navigate to your application settings.
2. Add a Webhook URL.
3. Store the Webhook Secret securely.

Your endpoint must:

• Accept HTTP POST requests
• Accept JSON payloads
• Return HTTP 200 quickly (after verification)

Webhook Request Structure

Each webhook request will include:

Headers

• X-Webhook-Timestamp
• X-Webhook-Signature
• Content-Type: application/json

Body

The body will contain a JSON event payload.

Example:

{
  "event": "document.signed",
  "agent_session_id": "as_123456",
  "handoff_id": "acme-7f3b2d2ca11qiqi",
  "timestamp": "2026-03-03T14:12:22Z",
  "data": {
    "document_id": "doc_9988",
    "status": "completed"
  }
}

Webhook Security: Signature Verification

Every webhook is signed to ensure it genuinely originates from DocEndorse.

Your system must verify the signature before processing the payload.

⸻

How the Signature Is Created

The signature is generated using:

HMAC SHA256

The input used to generate the signature is:

timestamp + "." + raw_request_body

The secret used for HMAC is your Webhook Secret.

The result is sent in:

X-Webhook-Signature

⸻

How to Verify a Webhook

Your backend must:

1. Read the raw request body exactly as received.
2. Extract the X-Webhook-Timestamp header.
3. Extract the X-Webhook-Signature header.
4. Recreate the signed payload: timestamp + “.” + raw_body
5. Generate an HMAC SHA256 hash using your webhook secret.
6. Compare your generated signature with the header value.
7. Reject the request if the values do not match.

Example: Inspecting a Webhook with curl (Testing)

You can simulate receiving a webhook locally using curl:

curl -X POST https://yourapp.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Timestamp: 1710000000" \
  -H "X-Webhook-Signature: generated_signature_here" \
  -d '{
    "event": "document.signed",
    "agent_session_id": "as_123456",
    "handoff_id": "acme-7f3b2d2ca11qiqi",
    "timestamp": "2026-03-03T14:12:22Z"
  }'

Your endpoint should:

• Verify signature
• Return HTTP 200 if valid
• Return HTTP 401 or 403 if invalid

Preventing Replay Attacks

You should:

• Ensure the timestamp is recent (e.g., within 5 minutes).
• Reject requests with stale timestamps.
• Optionally store recent webhook signatures to prevent reuse.

⸻

Recommended Processing Flow

1. Receive webhook.
2. Verify signature.
3. Validate timestamp freshness.
4. Parse JSON payload.
5. Process event.
6. Return HTTP 200 quickly.

Avoid performing long-running tasks before responding. If needed, queue the job for background processing.

Important Notes

• Always verify the signature before parsing business logic.
• Never trust webhook payloads without validation.
• Log failed signature attempts for security auditing.
• Store your webhook secret securely.