Skip to main content
Mesh sends every event for a mode to one URL of yours. Your code switches on event.

Set your URL

The first time, the answer includes secret (whsec_…). It’s shown only then. Store it; it signs every webhook.
  • Test and live have separate URLs and secrets: a test key sets the test URL.
  • The URL must be a public https address (http only in test). Addresses that resolve to private or local networks are refused.
  • DELETE /v1/webhook-endpoint stops deliveries. PUT with "enabled": false pauses them.

What you receive

Answer any 2xx within 10 seconds. Do your processing after you answer.

Verify the signature

Mesh-Signature is t=<unix seconds>,v1=<hex>. For each v1, compute HMAC-SHA256(secret, t + "." + raw body) as hex, and accept when any matches, compared in constant time. Refuse a t more than 5 minutes old.
Verify against the raw body bytes, before any JSON parsing. Re-serialised JSON won’t match.

Delivery

  • At least once. The same event can arrive more than once, and a replay carries the same id. Deduplicate on Mesh-Event-Id.
  • Retries. Anything but a 2xx within 10 seconds is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, then every 12 hours, for up to 3 days.
  • Failing URLs. When a delivery runs out of retries, the URL shows failing_since and your team gets one email. The next successful delivery clears it. Mesh never disables your URL.
  • History. GET /v1/webhook-deliveries lists deliveries; GET /v1/webhook-deliveries/{deliveryId} shows each attempt, with the status and the start of your answer.
  • Replay. POST /v1/webhook-deliveries/{deliveryId}/retry sends it again now.
  • Test. POST /v1/webhook-endpoint/test sends a webhook.test event.
  • Kept for 30 days, then deleted.

Rotate the secret

POST /v1/webhook-endpoint/rotate-secret returns a new secret. For 24 hours every webhook carries two v1 signatures, one per secret, so you can switch without missing any.

Events

Polling instead

GET /v1/events lists the same events, newest first, with the same data (filters event, from, to). GET /v1/events/{eventId} reads one. Use it to catch up after downtime, or instead of webhooks.