Webhooks

Receive real-time notifications when data changes. Webhooks are configured separately from API keys in Admin > Webhooks, and fire for both CMS and external API writes of a single record. Bulk CSV / JSON imports only send events to webhooks that opt in (see Bulk Imports below).

Configuration

Create a webhook in Admin > Webhooks by providing a URL endpoint and optional event subscriptions.

  • URL - The HTTPS endpoint that will receive POST requests when events occur.
  • Event subscriptions - Select which tables and actions should trigger the webhook: create, update and delete for single-record writes, plus create-many and update-many for rows written by a bulk import. If no subscriptions are added, the webhook receives every single-record event from all tables, but no bulk import events.
  • Signing secret - Auto-generated for each webhook. Used to verify that payloads are authentic (see Verification docs).

How It Works

  1. A record is created, updated, or deleted (via CMS or API), or a bulk import creates or updates rows.
  2. The system checks which webhooks are subscribed to that event. Rows from a bulk import only match a subscription that includes create-many or update-many for that table.
  3. An event for each matching webhook is saved together with the change itself, so a saved change is never missing its events.
  4. The event is queued and sent as a POST request to the webhook's URL with the event payload.
  5. Your endpoint receives the payload and processes it.

Behavior

Deliveries never block the API response. Each attempt has a 5-second timeout. A delivery that fails (an error response, a redirect, a timeout or a network error) is retried up to 4 more times over about 10 minutes. If it still fails, it is kept as dead-lettered and a Super can replay it with POST /api/v1/webhooks/replay.
  • Sensitive fields (passwords, 2FA secrets) are automatically stripped from the record payload.
  • A delivery can occasionally arrive more than once. Use its deliveryId to ignore duplicates.

Bulk Imports

Rows written by a bulk import (a CSV or JSON upload in the Data Manager that creates new records or updates existing ones) only send events to a webhook that asks for them. To opt in, add a subscription for the table and tick create-many, update-many, or both.

  • Each row sends its own event, with the same event name and payload as a single-record write: product.create for a created row, product.update for an updated one.
  • Only rows that actually change send an event. Rows skipped because nothing changed, and rows that fail, send nothing.
  • Volume follows the file: a 10,000-row import sends 10,000 events to each opted-in webhook. Large imports send them batch by batch while the import runs. Make sure your endpoint can handle that load before you opt in.
  • create-many and update-many don't include single-record events. Tick create and update as well to receive both.
  • There is no bulk delete, so deletes always arrive one record at a time.

Next Steps

  • Payloads & Events - Payload format, headers, and event naming conventions.
  • Verification - How to verify webhook signatures with your signing secret.