Webhook

Supermetal pushes change events to HTTP endpoints in Debezium or Supermetal format. Rows batch into JSON arrays, bodies compress with gzip, Zstandard, or Brotli, rate limits apply by request count and byte throughput, and deterministic idempotency keys give consumers exactly once delivery.

Request Format

POST /webhooks/public/orders HTTP/1.1
Content-Type: application/json
Content-Encoding: gzip
Idempotency-Key: 019c4ab1-473b-783c-af83-b22a9aa26cff
X-Source-Schema: public
X-Source-Table: orders

[
    {"id": 1, "name": "Alice", "_sm_version": 1234, "_sm_deleted": false},
    {"id": 2, "name": "Bob", "_sm_version": 1235, "_sm_deleted": false}
]

Prerequisites

An HTTP endpoint that accepts POST with application/json.
Authentication credentials, if the endpoint requires them.

Setup

Endpoint

URL. Base endpoint (https://api.example.com/events).
Path template. Appended path with {schema} and {table} placeholders.

Example. Base https://api.example.com with path template webhooks/{schema}/{table} posts to https://api.example.com/webhooks/public/users.

Requests time out after 30 seconds by default.

Authentication (optional)

Method	Header
Bearer	`Authorization: Bearer <token>`
Basic	`Authorization: Basic <base64(user:pass)>`
Header	Custom name and value (`X-API-Key: secret`)

Message Format

Debezium or Supermetal. See Kafka message formats.

Headers

Header	Default	Description
`Idempotency-Key`	on	Deterministic deduplication key
`X-Source-Schema`	on	Source schema name
`X-Source-Table`	on	Source table name

Configure header names or disable individually.

Idempotency Key

Derived from source table, row identity, and commit timestamp. Retrying the same batch produces the same key. Keys are time sortable.

For predictable idempotency, keep batch configuration stable. Disable batching (Max Batch Size = 1) for per row keys.

Static Headers

Add custom headers to every request.

Batching

Option	Default	Description
Max Batch Size	`0` (unlimited)	Rows per request
Max Payload Bytes	`1 MB`	Request body size

Flushes when either limit triggers. Set Max Batch Size = 1 to disable batching.

Compression

Value	Content-Encoding
None
Gzip	`gzip`
Zstd	`zstd`
Br	`br`

Rate Limiting

Option	Default	Description
Max Requests/Second	`0` (unlimited)	Request rate
Max Bytes/Second	`0` (unlimited)	Bandwidth

Retry

Exponential backoff with jitter.

Option	Default	Description
Max Retries	`1024`	Attempts (`0` = unlimited)
Max Retry Duration	`1 hour`	Total time (`0` = unlimited)
Initial Backoff	`1s`	First delay
Max Backoff	`3 min`	Maximum delay