Webhooks
Register an endpoint that receives signed event payloads, pick its events, rotate its secret, pause or test it, and read and replay the delivery log.
By the end of this page you will know how to register a URL that Zuse Bifrost posts events to, what the events look like at a glance, how to keep the signing secret safe, and how to read the delivery log when a consumer misbehaves.
A webhook endpoint is a URL of yours that receives a signed POST every time a subscribed event happens in your team: a story approved, a release promoted, an incident opened. It is how pipelines, chat alerts and bespoke automations learn about work without polling. The endpoint belongs to the team you are working in; everyone in the team sees it, and its creator and the team owner manage it.
Before you begin
| You need | Why |
|---|---|
| A public https URL | The target must be reachable from the internet over https. Private addresses and plain http are refused. |
| To be in a team | Endpoints are filed under the team you are working in; switch teams first if you mean another. |
| A consumer that verifies signatures | Every delivery carries a ZG-Signature header. Signature verification shows the check. |
Where webhooks live
Open Account Settings → Webhooks. The page lists the team's endpoints, newest first:
| Column | What it shows |
|---|---|
| Endpoint | The name and the URL. |
| Events | How many events it subscribes to. |
| Status | Active, or Disabled when paused by a person or after too many failures. |
| Row menu | Send test delivery, Rotate secret, Disable or Enable, Delete. |
The Deliveries button opens the delivery log.
Create an endpoint
- Press Create Endpoint.
- Type a Name that says who listens, such as Deploy pipeline listener.
- Type the URL. It must be https, and its host must resolve to a public address.
- Tick the Events to subscribe to. They are grouped by family (teams, roles, tokens, projects, and every family that lands with the phases to come), with a Toggle per family and one for everything.
- Press Create endpoint.
A flyout shows the signing secret once, with a copy button. Store it in your consumer's secret store before pressing Done; it is kept encrypted afterwards and never shown again. Verify every delivery against it, as signature verification describes.
Choose events, not families, when you can: a consumer that handles only
release.released should subscribe to that alone, so a change elsewhere never
reaches it as noise.
Send a test delivery
- Open the endpoint's row menu and choose Send test delivery.
- A synthetic
project.createdpayload is queued, markedsynthetic: truein its data, and posted with a real signature. It appears in the delivery log like any other delivery, so you can see what your consumer answered.
Rotate the secret
- Open the row menu and choose Rotate secret, then confirm.
- The new secret is shown once in the flyout. Update your consumer; deliveries signed with the old secret stop verifying from the next delivery on.
Rotate when a secret may have been seen by someone who should not hold it, and on a schedule of your own choosing.
Pause and resume
- Choose Disable to stop deliveries to an endpoint without deleting it. Events that fire while it is paused are not queued for it.
- Choose Enable to resume. Re-enabling clears the endpoint's failure count, so an endpoint that was switched off after an outage starts with a clean slate.
An endpoint is also disabled on its own after a long run of consecutive failures, so a dead URL does not keep a retry ladder busy forever. The status column says so, and Enable brings it back once the consumer is fixed.
Delete an endpoint
- Open the row menu and choose Delete, then confirm.
- The endpoint and its delivery history are removed, and any retries still pending for it are dropped.
Read the delivery log
Press Deliveries on the webhooks page, or open Account Settings → Webhooks → Deliveries. The log lists every delivery the team's endpoints were sent, newest first, with tabs for All, Pending, Delivered, Failed and Dead; the tab is in the address, so a link to the dead-letter view survives a reload.
| Column | What it shows |
|---|---|
| Delivery | The endpoint's name (or deleted endpoint) and the event name. |
| Status | Pending, delivered, failed (will be retried) or dead (retries exhausted), with the HTTP status the consumer answered. |
| Attempts | How many times it has been posted. |
| Created | How long ago the event fired. |
| Row menu | Details, and Retry delivery on failed and dead rows. |
Details opens a flyout with the event, the status, the attempts, the HTTP status, when it was created and when the next attempt is due, the excerpt of the consumer's response body, and the full payload as JSON. That excerpt is usually the fastest way to see why a consumer rejected a delivery.
Replay deliveries
- For one delivery, open its row menu and choose Retry delivery. The row goes back to the start of the retry ladder and is posted again shortly.
- For everything dead-lettered in the last day, press Replay dead (24h) and confirm. The toast says how many were queued. Older dead rows stay as they are; replay them one by one if they still matter.
Only failed and dead deliveries can be retried; a delivered one is final.
All the fields
What happens next
Registering, pausing, rotating or deleting an endpoint announces nothing to other endpoints; the delivery log is the record. Every delivery is retried with exponential back-off before it is dead-lettered, as retries and delivery describes, and the same page explains what the status codes your consumer answers mean to the ladder.
Permissions
| Action | Who may do it |
|---|---|
| See the team's endpoints and deliveries | Every member of the team |
| Create an endpoint | Every member of the team, filed under the team they work in |
| Test, rotate, pause, resume, delete | The endpoint's creator and the team owner |
| Retry and replay deliveries | Every member of the team |
Frequently asked
Related
- Webhooks quickstart: a first consumer end to end.
- Security: secrets, allow-lists and what a consumer should check.
- API tokens: the credential for the other direction.
How is this guide?
Last updated on
API Tokens
Mint a personal access token for the REST API, the MCP server or a pipeline, scope it to a team and optionally one project, tick its abilities, and revoke it.
Projects
What a project is in Zuse Bifrost, the key that prefixes every reference in it, its lifecycle statuses and health, the client it is done for, and the pages that manage them.