> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strails.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Webhook behavior, configuration, and signature verification in the Strails Mock Sandbox.

## Default Webhook Configuration

| Setting                   | Default Value                                     |
| ------------------------- | ------------------------------------------------- |
| Webhook URL               | `https://httpbin.org/post`                        |
| Webhook Secret (HMAC key) | `sandbox-webhook-secret-do-not-use-in-production` |

## Setting a Custom Webhook URL

Fintechs can override the default webhook URL using the `setwebhook` endpoint:

```http theme={null}
POST https://sandbox.stablesrail.io/v1/setwebhook
Content-Type: application/json
x-api-key: <sandbox-api-key>

{
  "url": "https://your-domain.com/webhook",
  "enabled": true
}
```

## Webhook Signature Verification

Sandbox webhooks are signed with HMAC-SHA256 over the string `${timestamp}.${payload}`:

```text theme={null}
signature = HMAC-SHA256(
  key = "sandbox-webhook-secret-do-not-use-in-production",
  message = "<ISO-8601-timestamp>.<JSON-payload>"
)
```

The signature is sent in the `X-Strails-Signature` header, and the timestamp is in `X-Strails-Timestamp`.

> The webhook secret is **global to the sandbox environment**. It is not per-fintech and does not use production `API_HMAC_SECRET` or provider secrets.

## Sample Webhook Payload

```json theme={null}
{
  "eventId": "uuid-event-id",
  "eventType": "user.onboarded",
  "timestamp": "2026-07-29T14:45:00.000Z",
  "requestId": "req-s-a1b2c3d4e5f6g7h8i9j0",
  "fintechId": "c8fe1911-d292-4f84-aa88-e34ceeea5b65",
  "version": "1.0.0",
  "userId": "usr-s-...",
  "payload": {
    "firstName": "Sandbox",
    "lastName": "User",
    "onboardedAt": "2026-07-29T14:45:00.000Z"
  }
}
```