# Register an endpoint (/docs/webhooks/register-endpoint)

Webhooks are managed **only in the Swop app, while you're signed in**. An API key can't create, change or delete them. That's deliberate: a leaked key must never be able to redirect your "paid" notifications to someone else.

## 1. Build the endpoint [#1-build-the-endpoint]

Your endpoint is any HTTPS URL on your server that accepts a JSON `POST`, verifies the signature and returns `2xx`. Start with the verifier on [Verify signatures](/docs/webhooks/verify-signatures).

URL rules:

- **`https://` only.** `http://localhost` and `http://127.0.0.1` are allowed for local development.
- No username or password in the URL.
- Swop doesn't follow redirects, so register the exact final URL.
- One registration per URL. Registering the same URL twice returns `409`.

## 2. Add it in the Swop app [#2-add-it-in-the-swop-app]

1. Open **Dashboard → Developer → Webhooks** in the Swop web app.
2. Paste your URL and an optional label.
3. Choose events. **All events are selected by default** (`checkout.paid` and `payout.released`).
4. Save, then **copy the signing secret**. It starts with `whsec_` and is **shown once**. Store it as an environment variable such as `SWOP_WEBHOOK_SECRET`.

## 3. Send a test [#3-send-a-test]

Press **Send test** next to the webhook. Swop sends a signed `ping` to your URL right away and shows the HTTP status your server returned.

```json title="Test payload"
{
  "id": "evt_test_1a2b3c4d",
  "event": "ping",
  "createdAt": "2026-10-29T18:00:00.000Z",
  "data": { "message": "Swop webhook test" }
}
```

## Changing or rotating [#changing-or-rotating]

There's no edit. To change the URL, the events or the secret, **remove** the webhook and add it again; you'll get a new secret. Pending deliveries for a removed webhook are discarded.

## Seeing your webhooks [#seeing-your-webhooks]

The Developer page lists each webhook with its status: active or paused, when it last delivered, and how many deliveries in a row have failed. Swop pauses a webhook after 25 consecutive failures; see [Retries](/docs/webhooks/retries-and-dedup).
