Get started
Webhooks

Delivery and retries

Delivery and retries

Each delivery is a POST of one event to your endpoint. Answer any 2xx within 10 seconds to acknowledge it.

Delivery
POST /mountaya HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
User-Agent: Mountaya-Webhooks/1
Mountaya-Signature: t=1763111564,v1=ad18de77c0892dba398f210f0f3205666e41c17025feaf8d42ae5998d8545f5d
Mountaya-Event-Id: 019a8eed-e1ad-7753-b049-b0e20d79577a
Mountaya-Event-Type: organization.member.updated
Mountaya-Delivery-Attempt: 1

{"id":"019a8eed-e1ad-7753-b049-b0e20d79577a","object":"webhook_event","type":"organization.member.updated",…}

Answer fast

  • Answer 2xx within 10 seconds. Store or queue the event, answer, then do the slow work.
  • Never redirect. Mountaya does not follow a 3xx, so it counts as a failure. Register the final URL.
  • Refuse what does not verify. Answer 400 to a bad signature, and process nothing.

Only Mountaya-Signature is signed. The other Mountaya- headers restate the body to help you route it, so read the event from the verified body.

Retries

Any answer but a 2xx fails the attempt, and so does no answer within 10 seconds. A failed attempt is retried on this schedule, about 72 hours in all:

RetryAfter the attempt before
1Immediately
21 minute
35 minutes
430 minutes
52 hours
65 hours
710 hours
814 hours
920 hours
1020 hours

To ask for a pause, answer with a Retry-After header. Mountaya waits as long as you ask, within that schedule.

Duplicates and order

Mountaya delivers each event at least once. A retry after a lost answer delivers it again, with the same id. Record the ids you processed, and skip one you have seen.

Events arrive in no promised order. To order one resource's events, compare the version its data.object carries, or read the resource itself when order matters.

Failures and health

Every failed attempt names its kind and whose it is. A receiver failure is yours: a timeout, a refused connection, a TLS error, a redirect or a non-2xx status. A Mountaya failure is ours, and never counts against your endpoint.

When every delivery to an endpoint has failed for 24 hours, Mountaya emails the organization's owners and admins. At 72 hours, it disables the endpoint. It does neither while it detects a delivery problem of its own.

curl -s "https://api.mountaya.com/v1/organizations/$MOUNTAYA_ORGANIZATION_ID/webhook-health?window=24h" \
  -H "X-API-Key: $MOUNTAYA_MANAGEMENT_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  | jq '.data.totals | {availability, eventual_success_rate, response_time_p95_ms}'

The Mountaya app shows the same report under Organization → Webhooks.

Next steps

Last updated