# What is a webhook?

A webhook is an HTTP request that a service sends to your URL when something
happens. Your code learns about the event without polling for it.

**Runtime posts every sandbox, snapshot and volume lifecycle event to your URL.
Each post is signed with HMAC-SHA256, and Runtime retries it for about three
days. You get a delivery log and a test send, at no extra charge.** Both SDKs
check the signature in one call. They refuse a signature older than five minutes
([webhooks](/docs/observability#webhooks)).

## Webhooks or polling

GitHub's documentation states the difference simply. Webhooks "receive data as
it happens, as opposed to polling an API (calling an API intermittently) to see
if data is available". Polling many resources quickly hits
[rate limits](/glossary/api-rate-limit). A webhook arrives only when there is
news.

## What a good webhook sender does

| Practice                      | Why                                  | Runtime                                                    |
| ----------------------------- | ------------------------------------ | ---------------------------------------------------------- |
| Signs each delivery           | Anyone can post to your URL          | `Runtime-Signature: t=…,v1=…`, HMAC-SHA256 of `{t}.{body}` |
| Timestamps the signature      | A captured request could be replayed | The SDKs refuse one older than five minutes                |
| Gives each event an id        | Retries mean you may see one twice   | `Runtime-Webhook-Id`, the same on every attempt            |
| Retries failures with backoff | Your endpoint will be down sometimes | Ten attempts over about three days                         |
| Keeps a log you can read      | "Did it send?" needs an answer       | Deliveries, attempts and status codes, kept 14 days        |

## Receiving one

Return any 2xx status within 10 seconds, then do the slow work. Verify the
signature over the raw body, before you parse the JSON. A re-serialized body no
longer matches. Deliveries are not guaranteed to arrive in order, so sort them
by `createdAt` ([check the signature](/docs/observability#check-the-signature)).

## Related

- [How to receive webhooks](/how-to/receive-webhooks)
- [How to verify a webhook signature](/how-to/verify-a-webhook-signature)
- [What is an API rate limit?](/glossary/api-rate-limit)
- [What is an idempotency key?](/glossary/idempotency-key)

## Sources

Checked 25 October 2026.

- [About webhooks, GitHub Docs](https://docs.github.com/en/webhooks/about-webhooks)
- [Runtime metrics, events and webhooks](/docs/observability)