Reference

Webhooks

Outbound endpoints, inbound receivers, signatures, delivery state, retry, replay, filters, idempotency receipts, diagnostics, and event payload contracts.

RealtimeRealtime & eventsWebSocket, SSE, event envelopes, subscription filters, replay, and field-name-only delivery.MCPMCP referenceJSON-RPC methods, resource metadata, token model, tools, resources, prompts, errors, and observability.CLICLI command referenceEvery command group, subcommand, flag, sample output, and exit code for automation and CI.ErrorsErrors referenceCanonical error envelopes, HTTP status mapping, machine-readable codes, reason codes, and correlation IDs.LimitsLimits & quotasRate limits, hard and soft quotas, budget enforcement, usage metering, and retry guidance.

Webhooks are a peer projection of Vadyl's canonical event and subscription surfaces. Outbound deliveries are durable rows with attempt history. Inbound receivers verify signatures before parsing and deduplicate through receipts.

Management routes

GET    /api/webhooks/endpoints
POST   /api/webhooks/endpoints
GET    /api/webhooks/endpoints/{id}
PUT    /api/webhooks/endpoints/{id}
DELETE /api/webhooks/endpoints/{id}
POST   /api/webhooks/endpoints/{id}/rotate-secret
GET    /api/webhooks/endpoints/{endpointId}/deliveries

GET    /api/webhooks/receivers
POST   /api/webhooks/receivers
GET    /api/webhooks/receivers/{id}
PUT    /api/webhooks/receivers/{id}
DELETE /api/webhooks/receivers/{id}
POST   /api/webhooks/inbound/{publicReceiverKey}
GET    /api/webhooks/diagnostics

Create an outbound endpoint

create-webhook-endpoint.example

curl -X POST https://api.vadyl.app/v1/webhooks/endpoints \
  -H "Authorization: Bearer $VADYL_TOKEN" \
  -H "X-Vadyl-Tenant: acme" \
  -H "X-Vadyl-Project: billing" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/vadyl",
    "description": "Billing events",
    "filter": { "op": "startsWith", "path": "$.type", "value": "order." },
    "retryPolicy": { "maxAttempts": 10, "baseDelaySeconds": 30 },
    "signingSecretRef": "secret:WEBHOOK_SIGNING_KEY"
  }'

Signature verification

The signature covers the exact raw bytes delivered to your server. Verify before JSON parsing. The canonical header format is t=unixTimestamp,v1=hexHmacSha256.

const payload = await request.arrayBuffer();
const header = request.headers.get("Vadyl-Signature");
const expected = hmacSha256(secret, timestamp + "." + rawBytes(payload));
timingSafeEqual(expected, signatureFrom(header));

Outbound delivery states

State	Meaning
`Pending`	Delivery row is eligible for claim.
`Claimed`	A scanner owns this attempt under lease.
`Succeeded`	Receiver returned a configured success status.
`RetryScheduled`	Attempt failed and next delivery time is scheduled with jitter.
`DeadLettered`	Retry policy exhausted or permanent failure classification.

Inbound receiver

receive-inbound.example

curl -X POST https://api.vadyl.app/v1/webhooks/inbound/rcv_01HXZ \
  -H "Vadyl-Signature: t=1778157600,v1=4e7..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "stripe.charge.succeeded", "id": "evt_external_123", "data": { "charge": "ch_123" } }'

Replay and diagnostics

POST /api/webhooks/deliveries/{deliveryId}/replay
GET  /api/webhooks/endpoints/{endpointId}/deliveries
GET  /api/webhooks/diagnostics

Replay is idempotent: a delivery attempt is new, but the canonical event identity and receiver idempotency semantics remain stable.

Realtime & events

MCP