Help / API

/v1/webhooks

Register and manage webhook subscriptions programmatically, the same real-time callbacks you can set up by hand on the Webhooks tab of Admin Center → API, but driven from your own code so an installed integration can wire up its own delivery endpoint without an admin clicking through the dashboard.

For the delivery contract itself (the request envelope, the X-42min-Webhook-Signature header, how to verify it, the retry schedule, and auto-pause behavior), see API & webhooks. This page is the management surface; that page is the receiving side.

The per-credential sandbox

This is the one rule that makes /v1/webhooks behave differently from the rest of the API:

A credential only ever sees and mutates the webhooks it created.

Concretely:

• Webhooks created through this API by a PAT are owned by that token. Webhooks created by an OAuth client are owned by that client (all of the client's access tokens share one sandbox: the binding is the stable client_id, so a token refresh doesn't orphan anything; a PAT, by contrast, is bound to that specific token, so rotating the PAT leaves its webhooks unreachable from the new token).
• Webhooks created in the admin UI are invisible to /v1/webhooks, and webhooks created over the API don't appear in another credential's listing. The admin UI still sees every webhook in the account, so the sandbox is one-directional.
• Two different integrations that legitimately point at the same ingestion URL are two real subscribers and both receive every matching event, because the duplicate-URL check is scoped to your own sandbox, not the whole account.

Because of the sandbox, GET /v1/webhooks returning [] does not mean the account has no webhooks, only that this credential created none.

Conventions specific to this resource

• Scopes: webhooks:read for the GETs, webhooks:write for every mutation (create, update, delete, rotate-secret, test). See Scopes.
• No Idempotency-Key, no If-Match. Unlike /v1/bookings, the webhook endpoints don't take an idempotency key or an ETag, and they aren't optimistically locked. Last write wins.
• The signing secret is shown exactly once. It is server-generated (you can't supply your own) and appears as signing_secret only in the POST (create) and rotate-secret responses. It is never returned by any GET. Lost it? Rotate.
• Account ceiling: 42 webhooks. The cap is account-wide across every credential and the admin UI combined, not 42 per credential.

The webhook object

{
  "id": "01H…",
  "url": "https://hooks.example.com/42min",
  "events": ["booking_created", "booking_updated"],
  "status": "active",
  "description": "Prod CRM sync",
  "paused_reason": null,
  "last_delivery_at": "2026-05-18T14:03:00.000Z",
  "last_delivery_ok": true,
  "created_at": "2026-05-10T09:00:00.000Z",
  "updated_at": "2026-05-18T14:03:00.000Z",
  "signing_secret": "42min_wh_…"
}

• status is active or paused. paused_reason is set when 42min auto-paused the hook (after 5 consecutive failed deliveries) and is null otherwise.
• last_delivery_ok is true / false / null (never delivered yet).
• signing_secret is present only on create and rotate-secret responses.

GET /v1/webhooks

List the webhooks this credential created.

Returns a plain array (newest first). This endpoint is not paginated.

{
  "data": [ { "id": "01H…", "url": "https://…", "events": ["booking_created"], "status": "active", "…": "…" } ],
  "meta": { "request_id": "req_…" }
}

curl

curl -H "Authorization: Bearer $TOKEN" \
  https://api.42min.us/v1/webhooks

GET /v1/webhooks/:id

Return one webhook this credential created.

Common errors

• 404 webhook.notFound: no such webhook in this credential's sandbox (it may exist for another credential or in the admin UI; you just can't see it).

POST /v1/webhooks

Create a webhook subscription.

Body

{
  "url": "https://hooks.example.com/42min",
  "events": ["booking_created", "booking_updated", "event_type_updated"],
  "description": "Prod CRM sync"
}

Response

201 Created with the webhook object including signing_secret. This is the only GET-style payload that ever carries the secret on create. Store it now; you'll need it to verify deliveries and it is never shown again.

curl

curl -X POST https://api.42min.us/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/42min",
    "events": ["booking_created", "booking_updated"],
    "description": "Prod CRM sync"
  }'

Common errors

• 400: url isn't a public HTTPS endpoint, or events is empty / contains an unknown event name.
• 409 webhook.duplicateUrl: this credential already has a webhook on that URL.
• 409: the account is at the 42-webhook ceiling.

PATCH /v1/webhooks/:id

Update a webhook. All fields optional; only those present are changed.

Body

{
  "url": "https://hooks.example.com/42min/v2",
  "events": ["booking_created", "booking_canceled"],
  "description": "Prod CRM sync (v2)",
  "status": "active"
}

Response

200 OK with the updated webhook object (no signing_secret).

curl

# Resume an auto-paused webhook
curl -X PATCH https://api.42min.us/v1/webhooks/01H… \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"active"}'

Common errors

• 404 webhook.notFound: not in this credential's sandbox.
• 400 / 409: same URL validation and duplicate-URL rules as create.

DELETE /v1/webhooks/:id

Permanently delete a webhook and its delivery history.

Response

204 No Content, with an empty body.

Common errors

• 404 webhook.notFound: not in this credential's sandbox.

POST /v1/webhooks/:id/rotate-secret

Issue a new signing secret. The old secret stops being valid immediately, so update your verifier before you call this, or accept a brief window of signature failures.

Response

200 OK with the webhook object including the new signing_secret, the second and last place the secret is ever returned.

curl

curl -X POST https://api.42min.us/v1/webhooks/01H…/rotate-secret \
  -H "Authorization: Bearer $TOKEN"

POST /v1/webhooks/:id/test

Enqueue a synthetic booking.created delivery so you can confirm your endpoint is reachable and your signature check works. The payload's data.booking is obviously fake ("test": true, id: "test-booking-id").

Response

200 OK:

{ "data": { "ok": true, "delivery_id": "01H…" }, "meta": { "request_id": "req_…" } }

The delivery is queued, not synchronous, so poll /deliveries with the returned delivery_id to see the outcome.

GET /v1/webhooks/:id/deliveries

The 50 most recent delivery attempts for this webhook, newest first. Older attempts are pruned after 30 days.

Response

{
  "data": [
    {
      "id": "01H…",
      "event": "booking_created",
      "attempt": 1,
      "status_code": 200,
      "error": null,
      "delivered_at": "2026-05-18T14:03:01.000Z",
      "created_at": "2026-05-18T14:03:00.000Z"
    }
  ],
  "meta": { "request_id": "req_…" }
}

• status_code is the HTTP status your endpoint returned (null if the request never completed: DNS failure, timeout, connection refused).
• error carries the failure reason when there is one; null on success.
• delivered_at is set only once a 2xx is received; it stays null for attempts that failed or are still pending.

Event names

The events array you send to create/update uses the enum (underscore) form. The event field in the delivered envelope and the X-42min-Webhook-Event header use the dot form. They map one-to-one:

event_type.updated / event_type.deleted fire from dashboard changes, since there are no public write endpoints for event types yet, but the webhooks let an integration keep its mirror of your event-type catalog in sync.

Catch-up after a pause. If a webhook was auto-paused and you missed booking.* events, reconcile with GET /v1/bookings?updated_since=…&sort=updated_at_asc rather than guessing: it returns every booking touched since a timestamp, in stable ascending order, ready to page through.

Where this sits

• Receiving, verifying, retries, auto-pause, the activity log → API & webhooks.
• Minting the PAT or OAuth client that calls this API → Authentication.
• The exact scope each endpoint needs → Scopes.