---
title: "Subscribe a webhook to a list's changes"
method: POST
path: "/api/v1/lists/{id}/webhooks"
tags: ["webhooks"]
---

# Subscribe a webhook to a list's changes

`POST /api/v1/lists/{id}/webhooks`

## Request

- Base URL: `https://www.listdrop.co`
- URL: `https://www.listdrop.co/api/v1/lists/{id}/webhooks`
- Auth: OAuth 2 (authorization code, authorization URL `https://www.listdrop.co/oauth/authorize`, token URL `https://www.listdrop.co/api/oauth/token`, scopes: `lists:read`)

Registers an https endpoint that receives a JSON POST whenever the list's content changes (events: added, removed, edited, sorted, renamed, deleted). The list must be visible to the connected account. Deliveries carry X-ListDrop-Event and X-ListDrop-Signature: sha256=<hex HMAC-SHA256 of the raw body> using the per-hook secret returned ONCE here. Ten consecutive failures disable the hook. Caps: 3 hooks per list, 20 per account.

## Path parameters

- `id` string, required

## Request body

- object
  - `url` string, uri, required: https endpoint to POST deliveries to.

## Response `201`

Registered. The secret appears only in this response.

- WebhookCreated
  - `id` string, required
  - `listId` string, required
  - `url` string, uri, required
  - `secret` string, required: HMAC-SHA256 signing secret (whsec_…). Shown exactly once — store it now.
  - `message` string, required

## Other responses

- `400`: Bad URL (must be public https) or webhook cap reached.
- `401`: Missing/invalid bearer token, or missing the lists:read scope.
- `404`: List not found or not visible to this account.
- `429`: Rate limit hit. Honor Retry-After.

---

[API](https://skmtc.dev/listdrop/apis/listdrop-public-api.md) · [All operations](https://skmtc.dev/listdrop/apis/listdrop-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/listdrop/apis/listdrop-public-api/revisions/699b5367e2f3?raw)