---
title: "Webhooks"
url: "/help/buuk/webhooks"
updated: "2026-11-13T18:45:42.492Z"
---
# Webhooks

Open **Settings → Developers** and use the **Webhooks** tab. Add an HTTPS endpoint, tick the events it should receive, and press **Create endpoint**. Outbound webhooks are a Growth capability; other plans see the gate when they try to create one.

![Settings → Developers, Webhooks tab: add a notification URL, pick events, and check recent deliveries.](/api/media/assets/e51df076-bcc4-470c-bae6-cdf13a2085f0)

## Events

Three article events exist, and every endpoint picks which ones it wants:

- `article.published` — an article, guide, or FAQ went live (Published).
- `article.updated` — published content changed (Updated).
- `article.archived` — a page was pulled out of the public site (Archived).

The payload is a JSON body with an event id, the event name, the workspace, a timestamp, and a data object carrying the article’s id, title, slug, kind, public URL, and publish date.

## Verify the signature

When an endpoint is created, Buuk shows a signing secret exactly once. Delivered requests carry an `X-Buuk-Signature` header — an HMAC-SHA256 of the raw body keyed with that secret, prefixed `sha256=` — plus an `X-Buuk-Event` header. Compute the same HMAC over the untouched request body on your side and compare before trusting the payload. Losing the secret means deleting and recreating the endpoint.

## Managing endpoints

- Send test fires a real request so you can confirm wiring without waiting for a publish.
- The pause toggle stops deliveries without deleting the endpoint; Resume turns them back on.
- Delete removes the endpoint permanently and stops its deliveries immediately.

## The delivery log

The Recent deliveries table below the endpoints lists each attempt with the event, the HTTP response status, the attempt count, and the time. A red row shows the error inline — a timeout, a private address Buuk refused to POST to, or a non-2xx status.

> [!NOTE]
> Each event delivery is attempted once, with an 8-second timeout. If a consumer was down at the wrong moment, use Send test to redeliver and then re-sync that endpoint from your own data.

## Deploy hooks

The next tab over, **Deploy hooks**, rebuilds your own sites when content changes. Create a hook for Vercel or Netlify with a name and a public HTTPS hook URL, and choose trigger events such as `content_published` (help content published), `spec_updated` (API docs updated), or per-kind events for articles, guides, FAQs, and changelog entries. Publishing an article fires every matching active hook, and the panel records each hook’s last trigger and status.

The panel also tracks preview deployments — builds triggered by a pull request, a push, or your own manual test — with their build status and preview URL, so you can check a changeset before it ships. Point a deploy hook at your own URL to rebuild a mirrored docs site, warm caches, or ping a channel.

## Worked example

A docs mirror runs on Netlify. Add a deploy hook for `content_published`. Every time an editor publishes, Netlify rebuilds the mirror so it never drifts from the live help center. Before relying on it, press **Send test** and confirm the build starts.

## Troubleshooting

**My endpoint rejects every delivery**

Check two headers first: compare the `X-Buuk-Signature` HMAC against the raw body (not re-serialized JSON), and make sure the URL is public HTTPS — loopback, private, and metadata addresses are refused.

**Deliveries show a timeout or blocked error**

Your consumer has 8 seconds to respond to each delivery. Long queues should return 202 and work asynchronously. Redirect responses are treated as failures too, so point the endpoint straight at your final host.

**I lost the endpoint secret**

The secret is shown once at creation and cannot be viewed again. Delete the endpoint and create a replacement, then update the stores that verify signatures.

## Related

- Tokens and MCP, the pull side of the API: [API tokens and MCP](./api-tokens-and-mcp).
- Rebuild timing around publish: [Publish your help center](./publish-your-help-center).
- Event sources connected in-app: [Integrations overview](./connect-integrations).
- Where the webhook gate lives: [Plans and billing](./plans-and-billing).