# Callbacks

:::note

Webhooks are currently not offered. Use callbacks to receive notifications about signature request events.

:::

## Setting Up Callbacks

Configure callbacks to receive real-time updates:

```json
{
  "callback_success_url": "https://your-app.com/webhooks/skribble/success",
  "callback_error_url": "https://your-app.com/webhooks/skribble/error",
  "callback_update_url": "https://your-app.com/webhooks/skribble/update"
}
```

## Callback Types

| Type | Triggered When |
|------|----------------|
| `SUCCESS` | All signers have signed |
| `UPDATE` | A signer has signed (partial completion) |
| `ERROR` | An error occurred |
| `START_SIGN` | A signer started signing |
| `INITIATE` | Request was initiated |
| `IDENT_ERROR` | Identification error |

## Callback URL Placeholders

You can use placeholders in callback URLs that Skribble will replace with actual values:

| Placeholder | Replaced With |
|-------------|---------------|
| `SKRIBBLE_SIGNATURE_REQUEST_ID` | The signature request ID |
| `SKRIBBLE_DOCUMENT_ID` | The current document ID |
| `SKRIBBLE_SIGNATURE_ID` | The signer's unique signature ID |

:::note

Callback URLs are HTML-encoded before being called. Avoid pre-encoding your URLs to prevent double-encoding issues.

:::

## Callback Retries

Skribble automatically retries failed callbacks (non-2xx responses) **every 10 minutes for up to 2 hours**, then stops. Your callback endpoint can return a `Retry-After` header to control retry timing.

## Checking Callback Delivery

To confirm whether a callback has been executed — or to identify errors that occurred during the callback process — use the [Get callback details for a signature request](/api/sign-v2/signature-handling#get-callback-details-for-a-signature-request) endpoint:

```
GET /signature-requests/{SR_ID}/callbacks
```

If no callbacks have been triggered yet, the response is an empty array. Otherwise it contains an array of `callback` objects that have already been executed, including their delivery status.

## Callback Security (mTLS)

Callbacks support TLS mutual authentication (mTLS). If the callback endpoint (your side) asks for a client authentication during the TLS handshake, Skribble will authenticate itself with an X.509 certificate for `api.skribble.com`.

The callback will additionally send the related root certificate from GlobalSign as certificate authority as well as the related intermediate certificate by Alpha SSL as certificate provider.

:::info

Valid until: **10.12.2026**

:::

| Certificate | Download |
|-------------|----------|
| X.509 certificate for `api.skribble.com` | [api.skribble.com.cer](https://www.skribble.com/ext/api/certificates/api.skribble.com.cer) |
| Intermediate certificate by Alpha SSL | [AlphaSSL_CA.cer](https://www.skribble.com/ext/api/certificates/AlphaSSL_CA.cer) |
| Root certificate from GlobalSign | [GlobalSign_Root_CA.cer](https://www.skribble.com/ext/api/certificates/GlobalSign_Root_CA.cer) |

## Callback Best Practices

1. **Acknowledge quickly**: Return 200 within 5 seconds
2. **Process asynchronously**: Queue the work, respond immediately
3. **Handle idempotency**: The same callback may be delivered multiple times
4. **Verify authenticity**: Validate callback requests come from Skribble (mTLS or IP allowlist)