Callbacks & Events

The webhook/callback system in Dropbox Sign — how applications get notified about signature request events in real-time.

Callback (Webhook)

Brief: An HTTP POST request sent by Dropbox Sign to a configured server when a significant event occurs (e.g., a signer signs, a request completes).

Description: Callbacks (webhooks) are Dropbox Sign’s push-based notification mechanism. Instead of polling the API to check status, a callback URL is configured, and Dropbox Sign sends an HTTP POST to that URL whenever something happens. The receiving server must respond with "Hello API Event Received" (HTTP 200) to acknowledge receipt.

Key Behaviors:

• Sent as HTTP POST with a JSON payload
• Endpoint must respond with exactly: Hello API Event Received
• If the endpoint doesn’t respond correctly, Dropbox Sign retries with exponential backoff
• Retries occur over approximately 3 days before giving up
• Callbacks include a hash for verification (to confirm authenticity)

Callback URL Configuration:

• Account-level: Set in Account settings (receives events for all requests from that account)
• App-level: Set in API App configuration (receives events for requests made with that app’s client_id)
• App-level callback URLs take priority over account-level when both are configured

Payload Structure:

1
{
2
  "event": {
3
    "event_type": "signature_request_signed",
4
    "event_time": "1669926463",
5
    "event_hash": "abc123...",
6
    "event_metadata": {
7
      "related_signature_id": "...",
8
      "reported_for_account_id": "...",
9
      "reported_for_app_id": "..."
10
    }
11
  },
12
  "signature_request": { },
13
  "account": { }
14
}

Verification: To verify a callback is genuinely from Dropbox Sign:

1. Compute HMAC-SHA256 of event_time + event_type using the API key as the secret
2. Compare with event_hash in the payload
3. Reject if they don’t match

Event Types

Brief: The specific occurrence that triggered a callback notification.

Signature Request Events

Template Events

Account Events

Event Ordering (typical successful flow):

signature_request_sent
  → signature_request_viewed (per signer)
  → signature_request_signed (per signer)
  → signature_request_all_signed
  → signature_request_downloadable

Important Distinctions:

• signature_request_all_signed means every required signer has completed their part of the request. For workflows that only need signing status, this may be enough.
• signature_request_downloadable means Dropbox Sign has finished generating the final files. Document generation can take extra time after all signers finish, especially for larger or more complex documents. Wait for this event before downloading final files.
• Events may arrive out of order due to network conditions.
• The same event may be received more than once during retries — implement idempotent handling.

Related docs: See the Events Overview and Events Walkthrough for callback setup and verification.

Callback Testing

Brief: Methods to test callback endpoints during development.

Description: Dropbox Sign provides ways to test callback handling:

1. Test mode requests: Create requests with test_mode=1. Events still fire to the callback URL.
2. Callback test endpoint: Use the API to trigger a test callback event to verify the endpoint is reachable and responding correctly.
3. Event log: Check the account’s event log in the dashboard to see sent callbacks and their delivery status.

Debugging Tips:

• Ensure the endpoint is publicly accessible (not localhost)
• Verify the response is exactly Hello API Event Received (no extra whitespace or formatting)
• Check that the endpoint responds within 25 seconds (timeout threshold)
• Use the event hash to verify the HMAC is computed correctly