Webhooks overview

​

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

• 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

​

Event types

​

Anatomy of a delivery

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).
• X-Alvys-Attempt — the delivery attempt number (starts at 1, increments on each retry).

{
  "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)" }
  }
}

​

Verifying signatures

{timestamp}.{eventId}.{raw_request_body}

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.

​

Delivery guarantees

​

Managing webhooks

​

Monitoring and troubleshooting

​

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