> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hellosign.com/llms.txt.
> For full documentation content, see https://developers.hellosign.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hellosign.com/_mcp/server.

# Callbacks & Events

> Webhook notifications, event types, and callback handling in the Dropbox Sign API.

# 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:**
```json
{
  "event": {
    "event_type": "signature_request_signed",
    "event_time": "1669926463",
    "event_hash": "abc123...",
    "event_metadata": {
      "related_signature_id": "...",
      "reported_for_account_id": "...",
      "reported_for_app_id": "..."
    }
  },
  "signature_request": { },
  "account": { }
}
```

**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

| Event Type | Description | When It Fires |
| --- | --- | --- |
| `signature_request_viewed` | A signer viewed the request | Signer opens the signing page |
| `signature_request_signed` | A signer completed signing | One signer finishes their fields |
| `signature_request_sent` | Request was sent to signers | Initial send or resend |
| `signature_request_all_signed` | All signers have signed | Last signer completes required fields |
| `signature_request_downloadable` | Final PDF is ready | Document generation is complete |
| `signature_request_declined` | A signer declined | Signer explicitly declines |
| `signature_request_reassigned` | Request reassigned to new signer | Signer reassigns to someone else |
| `signature_request_remind` | A reminder was sent | Sender triggers a reminder |
| `signature_request_canceled` | Request was cancelled | Sender cancels the request |
| `signature_request_email_bounce` | Signer email bounced | Email delivery failed |
| `signature_request_invalid` | Request has an error | Processing or validation error |
| `signature_request_expired` | Request passed expiration date | Expiration date reached |
| `signature_request_prepared` | Request is ready for signers | Setup/processing complete |

### Template Events

| Event Type | Description |
| --- | --- |
| `template_created` | A new template was created |
| `template_error` | An error occurred creating/editing a template |

### Account Events

| Event Type | Description |
| --- | --- |
| `account_confirmed` | A new account confirmed their email |
| `sign_url_invalid` | An embedded sign URL has expired/been used |

**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](/docs/guides/events-and-callbacks/overview) and [Events Walkthrough](/docs/guides/events-and-callbacks/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