> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks overview
> Complete guide to Alvys webhooks — signed HTTPS event delivery, endpoint verification, signature validation, retries, event types, and the full webhook management API.
Webhooks let your system receive real-time updates from Alvys when business events occur. Instead of polling the API, Alvys sends an HTTPS POST request to your configured endpoint whenever a subscribed event is triggered.
Webhooks are configured per Subsidiary. Each Subsidiary maintains its own set of webhook subscriptions, and events are delivered only within that Subsidiary's context.
Webhooks are currently available by request. To enable this functionality for your account, contact your Customer Success Manager or Implementation Manager.
## How it works
1. **Subscribe** — create a webhook with an HTTPS endpoint URL and at least one subscribed event, either in the dashboard (**Settings → Connections → Webhooks**) or via the [Create webhook](/en/api/reference/webhooks/create-webhook-subscription) endpoint.
2. **Verify ownership** — when the webhook is enabled, Alvys sends a `webhook.verification` challenge to your endpoint. Your endpoint echoes the challenge back to prove ownership. See [Webhook Lifecycle & Configuration](/en/api/reference/webhooks/webhook-lifecycle-configuration).
3. **Receive events** — Alvys delivers each subscribed event as a signed HTTPS POST request to your endpoint.
4. **Validate and acknowledge** — your endpoint verifies the HMAC-SHA256 signature, deduplicates on the event ID, and returns a `2xx` response promptly.
5. **Retries** — failed deliveries are retried automatically. After 10 consecutive failed events, the webhook is disabled automatically.
All deliveries:
* Use HTTPS (TLS 1.2+)
* Are signed using HMAC-SHA256
* Follow an at-least-once delivery model
* Are retried automatically on transient failure
* Are disabled automatically after repeated delivery failures
To integrate successfully, your endpoint must verify signatures, handle retries safely, and implement idempotency.
## Event types
| Event | Fires when | Details |
| ---------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `load.status.changed` | A load's status transitions (e.g. `Covered` → `Dispatched`) | [Load Events](/en/api/reference/webhooks/load-events) |
| `load.changed` | Any meaningful load write — rate, appointments, stops, references, … | [Load Events](/en/api/reference/webhooks/load-events) |
| `trip.status.changed` | A trip's status transitions | [Trip Events](/en/api/reference/webhooks/trip-events) |
| `trip.changed` | Any meaningful trip write — carrier, driver, stops, appointments, rates, … | [Trip Events](/en/api/reference/webhooks/trip-events) |
| `webhook.verification` | Alvys verifies ownership of your endpoint (system event, not signed) | [Webhook Lifecycle & Configuration](/en/api/reference/webhooks/webhook-lifecycle-configuration) |
The authoritative list of valid event-type strings for your account is returned by [Get event types](/en/api/reference/webhooks/get-event-types) (`GET /api/p/v1/webhooks/event-types`).
`load.changed` and `trip.changed` events carry the full current snapshot of the record plus an optional `data.diff` node describing what changed — and, if you opt in, what the values were before. See [Change Diffs (data.diff)](/en/api/reference/webhooks/change-diffs).
## Anatomy of a delivery
When a subscribed event occurs, Alvys sends an HTTPS POST request to your configured endpoint.
Headers:
```
X-Alvys-Event: load.status.changed
X-Alvys-Event-Id: evt-123456
X-Alvys-Timestamp: 1699200000
X-Alvys-Signature: t=1699200000,v1=abcdef...
X-Alvys-Attempt: 1
```
* `X-Alvys-Event` — the event type.
* `X-Alvys-Event-Id` — unique identifier for the event. Remains the same across retry attempts; use it for idempotency.
* `X-Alvys-Timestamp` — Unix timestamp (seconds) used for signature generation.
* `X-Alvys-Signature` — HMAC-SHA256 signature (see [Verifying signatures](#verifying-signatures)).
* `X-Alvys-Attempt` — the delivery attempt number (starts at 1, increments on each retry).
Every event body uses the same envelope:
```json theme={null}
{
"id": "3cd9960e-ef75-446c-92e4-e9815f6e4024-1",
"type": "load.status.changed",
"timestamp": "2026-02-23T15:19:35.8794642+00:00",
"version": "v1",
"data": {
"load": { "...": "full current Load snapshot (matches GET /api/p/v1/loads)" }
}
}
```
The `data` object contains event-specific fields. For load and trip events it carries the full current snapshot of the record — the same shape the corresponding `GET` endpoint returns — so you can apply the current state directly without a follow-up request. See [Event Delivery & Reliability](/en/api/reference/webhooks/event-delivery-reliability#event-request-format) for the full request format.
## Verifying signatures
Every event delivery is signed so you can confirm it came from Alvys and was not tampered with. Verification requests (`webhook.verification`) are not signed.
The `X-Alvys-Signature` header has the format `t={timestamp},v1={signature}`, where the signature is an HMAC-SHA256 hash of:
```
{timestamp}.{eventId}.{raw_request_body}
```
To validate a delivery:
1. Extract the timestamp and signature value(s) from the `X-Alvys-Signature` header.
2. Construct the signed payload from the timestamp, event ID, and the exact raw request body — do not reformat or reserialize the JSON.
3. Compute an HMAC-SHA256 hash using your webhook's signing secret.
4. Compare against the provided signature(s) using constant-time comparison.
5. Return `401 Unauthorized` and do not process the event if no match is found.
During secret rotation the header carries two signatures (`v1` for the new secret, `v0` for the previous one) — accept either during the transition window. Rejecting requests whose timestamp is more than 5 minutes old reduces replay risk.
Full details, including transport requirements and secret management: [Security & Signature Verification](/en/api/reference/webhooks/security-signature-verification).
## Delivery guarantees
| Category | Behavior |
| ---------------- | ----------------------------------------------------------------------------- |
| Delivery model | At-least-once |
| Max attempts | 4 (initial + retries after \~10s, \~30s, \~60s) |
| Timeout | 30 seconds per attempt |
| Retry triggers | HTTP 500–599, 408, 429, network failure, or timeout |
| Duplicate events | Possible — deduplicate on `X-Alvys-Event-Id` |
| Global ordering | Not guaranteed |
| Auto-disable | After 10 consecutive failed events (counted per event, not per retry attempt) |
| Idempotency | Required |
A delivery succeeds when your endpoint returns HTTP `200–299`. Other 4xx responses (except 408 and 429) are permanent failures and are not retried. A successful delivery resets the consecutive-failure counter; once 10 distinct events fail consecutively, the webhook is disabled and must be manually re-enabled.
Acknowledge the event promptly after validation and persist processing asynchronously. This avoids timeouts, unnecessary retries, and accidental auto-disable.
See [Event Delivery & Reliability](/en/api/reference/webhooks/event-delivery-reliability) for the complete retry, timeout, and ordering semantics.
## Managing webhooks
Webhooks can be managed from the dashboard (**Settings → Connections → Webhooks**) or entirely via the API:
| Action | Endpoint | Reference |
| --------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Create a webhook | `POST /api/p/v1/webhooks` | [Create webhook subscription](/en/api/reference/webhooks/create-webhook-subscription) |
| List webhooks | `GET /api/p/v1/webhooks` | [List webhooks](/en/api/reference/webhooks/list-webhooks) |
| Get a webhook | `GET /api/p/v1/webhooks/{id}` | [Get webhook](/en/api/reference/webhooks/get-webhook) |
| Update a webhook | `PUT /api/p/v1/webhooks/{id}` | [Update webhook](/en/api/reference/webhooks/update-webhook) |
| Delete a webhook | `DELETE /api/p/v1/webhooks/{id}` | [Delete webhook](/en/api/reference/webhooks/delete-webhook) |
| Enable / disable | `POST /api/p/v1/webhooks/{id}/enable` · `/disable` | [Enable](/en/api/reference/webhooks/enable-webhook) · [Disable](/en/api/reference/webhooks/disable-webhook) |
| Verify ownership | `POST /api/p/v1/webhooks/{id}/verify` | [Verify webhook ownership](/en/api/reference/webhooks/verify-webhook-ownership) |
| Send a test event | `POST /api/p/v1/webhooks/{id}/test` | [Test webhook delivery](/en/api/reference/webhooks/test-webhook-delivery) |
| List event types | `GET /api/p/v1/webhooks/event-types` | [Get event types](/en/api/reference/webhooks/get-event-types) |
| Reveal signing secret | `POST /api/p/v1/webhooks/{id}/reveal-secret` | [Reveal webhook secret](/en/api/reference/webhooks/reveal-webhook-secret) |
| Rotate signing secret | `POST /api/p/v1/webhooks/{id}/rotate-secret` | [Rotate secret](/en/api/reference/webhooks/rotate-secret) |
Configuration details — states, endpoint verification, updating subscriptions, and the **Include previous values** option — are covered in [Webhook Lifecycle & Configuration](/en/api/reference/webhooks/webhook-lifecycle-configuration).
## Monitoring and troubleshooting
Every delivery attempt is logged and queryable:
| Action | Endpoint | Reference |
| ---------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| List delivery logs | `GET /api/p/v1/webhooks/{webhookId}/delivery-logs` | [List delivery logs](/en/api/reference/webhooks/list-delivery-logs) |
| Get delivery detail | `GET /api/p/v1/webhooks/{webhookId}/delivery-logs/{logId}` | [Get delivery log detail](/en/api/reference/webhooks/get-delivery-log-detail) |
| Export logs (CSV/JSON) | `GET /api/p/v1/webhooks/{webhookId}/delivery-logs/export` | [Export delivery logs](/en/api/reference/webhooks/export-delivery-logs) |
| Health metrics (1/7/30 days) | `GET /api/p/v1/webhooks/{webhookId}/health` | [Get webhook health metrics](/en/api/reference/webhooks/get-webhook-health-metrics) |
Use [Test webhook delivery](/en/api/reference/webhooks/test-webhook-delivery) to send a signed test payload to your endpoint and verify your signature logic end to end.
## Best practices
* **Verify every signature** before executing any business logic; return `401` on failure.
* **Deduplicate on `X-Alvys-Event-Id`** — delivery is at-least-once, so duplicates are expected.
* **Acknowledge fast** — return `2xx` after validation and process asynchronously to stay inside the 30-second window.
* **Don't rely on ordering** — tolerate retries, duplicates, and timing variations.
* **Use `data.diff` to filter noise** — ignore deliveries where `changes` is empty (parent cascades), and tolerate change kinds you don't recognize.
* **Support dual signatures** (`v1` and `v0`) so secret rotation never interrupts your integration.
* **Watch health metrics and delivery logs** so you catch failures before the auto-disable threshold.
## Next steps
Create, verify, update, and manage webhook subscriptions per Subsidiary.
Validate HMAC-SHA256 signatures and handle secret rotation.
At-least-once delivery, retries, timeouts, and auto-disable semantics.
React to exactly what changed with `changes` and `previousAttributes`.