Webhooks & Security

This section covers webhook authentication and verification in DocuWriter.ai. It explains how inbound and outbound webhooks secure data integrity and prevent replay attacks. You’ll learn signature handling, timestamp validation, and error handling with code examples.

Outbound Webhooks: Signing & Dispatching

When DocuWriter.ai pushes events to your systems, it signs each payload with HMAC-SHA256.

• Dispatch Headers

Inbound Webhooks: Verification (GitHub Example)

When DocuWriter.ai receives GitHub events for PR documentation, it verifies the signature before processing.

• Error Handling - 401 Unauthorized: Invalid or missing signature
• 400 Bad Request: Missing required payload fields
• 500 Internal Server Error: Unexpected exceptions

Timestamp Tolerance & Replay Protection

To guard against replay attacks, include and verify a timestamp in each payload.

• Include Timestamp

  {
    "event": "generation.created",
    "timestamp": "2025-07-08T10:30:14Z",
    "data": { ... }
  }

• Validation Steps - Parse timestamp from JSON.
• Convert to server time (UTC).
• Reject if older than ±5 minutes.
• Store processed payload IDs or timestamps to prevent duplicates.

Verification Flowchart

sequenceDiagram
    participant DW as DocuWriter.ai
    participant Client as Your Endpoint

    DW->>Client: POST /webhook<br/>Headers: X-DocuWriter-Signature, X-DocuWriter-Event
    Client->>Client: parsePayload()
    Client->>Client: verifySignature(rawBody, secret)
    Client->>Client: validateTimestamp(data.timestamp)
    alt Valid & Fresh
        Client->>Client: processEvent()
        Client-->>DW: HTTP 200 OK
    else Invalid or Stale
        Client-->>DW: HTTP 401 Unauthorized / 400 Bad Request
    end