> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weelkit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook setup

> Create a webhook endpoint, subscribe to events, and understand secrets, testing, and the delivery log.

An API webhook destination delivers each persisted article version to an HTTPS endpoint you control, signed with a shared secret. There is no remote schema and no field mapping — the payload always follows the organization contract described in [Webhook payload](https://docs.weelkit.com/integrations/webhook/payload.md).

## Create an endpoint

**1. Add the endpoint**

In **Organization settings → Integrations → API Webhook**, click **Add webhook**. Give it a name and the delivery URL.

The URL must be **HTTPS**. Private, loopback, and cloud-metadata hosts are rejected — the endpoint must be publicly reachable.

**2. Subscribe to events**

Select the events to deliver. The article delivery event is:

| Event | Delivered when |
| - | - |
| `article.version.created` | A new article version is persisted |

**3. Store the signing secret**

Weelkit generates a signing secret with the `whsec_` prefix and shows it **once**. Copy it into your secret manager before leaving the page — it cannot be displayed again.

**4. Test the connection**

Choose **Send test** on the endpoint. Weelkit delivers a `webhook.test` event with real headers and a real signature, but `article` set to `null`. Verify your endpoint accepts it and that [signature verification](https://docs.weelkit.com/integrations/webhook/signature-verification.md) passes.

## Rotate the secret

Rotate the signing secret whenever you suspect exposure or as part of routine credential hygiene. Rotation issues a new `whsec_` secret — again shown once — and bumps the endpoint's secret version. The old secret stops signing at once, and every later attempt, retries included, is signed with the new one. Make your verifier accept both secrets before you rotate; see [signature verification](https://docs.weelkit.com/integrations/webhook/signature-verification.md#secret-rotation) for the pattern.

## Activate and deactivate

An endpoint can be **active** or **inactive**. Inactive endpoints stop automatic deliveries and retries; events that occur while inactive are not queued for later. You can still choose **Send test** to check an inactive endpoint before activating it.

Three consecutive definitively failed deliveries deactivate the endpoint. Pending deliveries do not count as completed failures; an outcome-unknown delivery breaks the failure streak. Fix the receiver before turning **Active** back on.

## Delivery log

Choose **Deliveries** on the endpoint to see every delivery and its status:

| Status | Meaning |
| - | - |
| **Success** | Your endpoint returned a 2xx response. The delivery was accepted. |
| **Pending** | The delivery is waiting to be sent, or a failed attempt will be retried. |
| **Failed** | Your endpoint definitively rejected the delivery, or every attempt failed. |
| **Outcome unknown** | The request may or may not have reached you: a timeout or network loss after it was sent. It's never rewritten as failed. |

Webhook deliveries and receipts never change an article's status or address in Weelkit; only a connected CMS does.

The success rate uses the latest 100 recorded deliveries; unsent queued events do not count. Without recorded deliveries, it shows **—**. **Last accepted delivery** refers to the latest successful delivery, not the latest queued event.

## Retry schedule

A delivery gets at most **3 automatic attempts**: the first, then retries after at least **1 minute** and **5 minutes**. A longer `Retry-After` delays the retry further. Every retry reuses the **same event and operation identity** — the same `X-Weelkit-Event-Id` and `X-Weelkit-Operation-Id` headers — so your endpoint can deduplicate. See [Receipts and retries](https://docs.weelkit.com/integrations/webhook/receipts-and-retries.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.