Webhooks and CDC

Change data capture (CDC) sends TigerBeetle changes from a dedicated Parix database to downstream systems. Configure it from the database's Cluster > Change Data Capture page. When Parix manages webhook delivery, inspect attempts from the database's Webhooks page.

CDC and Webhooks are dedicated-plan surfaces. Shared Developer databases expose gateway, Query, Connect, Settings, and project metrics, but do not expose self-service CDC or webhook configuration.

Eligibility and access

To change CDC configuration, all of the following must be true:

• the database is on an eligible dedicated plan;
• you are an organization owner or administrator;
• a database profile exists; and
• the profile is not currently provisioning.

Provider and region availability is environment-specific. The create catalog and the database's active profile are authoritative; do not assume that every provider implemented by Parix is currently offered for new customer deployments.

CDC configuration has five lifecycle statuses: draft, queued, running, active, and error. A saved choice is not delivering events until it reaches active.

Choose a mode

Direct AMQP does not create entries in managed webhook delivery history. The Webhooks page describes only HTTPS attempts made by Managed AMQP.

Changing modes also removes saved mode-specific configuration. Leaving Direct AMQP deletes its stored password. Leaving Managed AMQP deletes its saved destinations and destination secrets. If you later switch back, recreate those destinations and re-enter their secrets. Confirm the replacement path before selecting another mode or disabling CDC.

Configure Direct AMQP

Direct AMQP requires a publicly reachable literal IP address. Hostnames and private, loopback, link-local, metadata, or reserved addresses are rejected by the egress policy.

Enter:

• host as a literal IPv4 or IPv6 address;
• port from 1 through 65535;
• username and password;
• virtual host (defaults to /);
• exchange and routing key;
• whether TLS is enabled; and
• whether publish confirmations are required (enabled by default).

Provide the password on the first save. On later edits, leave the password blank to retain the stored secret; entering a value replaces it. Prefer a TLS-protected endpoint and a credential limited to the configured virtual host/exchange.

Before selecting Save and apply, verify from the receiving system that the address and port are publicly reachable and that its AMQP user can authenticate and publish to the chosen exchange/routing key. Parix cannot apply a private hostname or traverse your private network implicitly.

Configure Managed AMQP webhooks

Managed AMQP needs at least one active webhook destination. Add destinations from the Change Data Capture form, then choose which ones should receive events.

For each destination:

1. Give it a unique descriptive name (1–80 characters).
2. Enter a public, literal-IP HTTPS URL. Managed delivery uses the HTTPS port and does not follow redirects.
3. Do not embed a username, password, or token in the URL.
4. Choose an authentication mode: none, static header, or HMAC SHA-256.
5. Mark the destination active when it is ready to receive events.

The URL cannot target private, loopback, link-local, metadata, or reserved addresses. A DNS hostname is not accepted in place of the literal public IP. Keep the destination certificate and network listener valid for HTTPS on port 443.

Authentication modes

Provide a secret when first enabling static-header or HMAC authentication. On later edits, leave the secret field blank to retain its stored value; entering a value rotates it. Inactive destinations are saved but ignored by delivery.

Managed delivery contract

Parix sends an HTTP POST with content-type: application/json. The event body has this shape:

{
  "id": "<event-id>",
  "timestamp": "<event-timestamp>",
  "databaseProfileId": "<profile-id>",
  "routingKey": null,
  "exchange": null,
  "payload": {},
  "ingestedAt": "<ingestion-timestamp>"
}

routingKey and exchange are strings when provided by the event and null otherwise. payload can be any valid JSON value—not only an object—so receivers must accept objects, arrays, strings, numbers, booleans, and null.

Every request includes:

content-type: application/json
user-agent: <Parix delivery agent>
x-parix-event-id: <event-id>
x-parix-database-profile-id: <profile-id>

Use the event id or x-parix-event-id as the receiver's idempotency key.

Verify an HMAC request

HMAC destinations also receive:

x-parix-signature: sha256=<lowercase-hex-digest>
x-parix-signature-ts: <timestamp-in-milliseconds>

Parix signs this exact byte sequence with the configured secret:

<x-parix-signature-ts>.<raw-request-body>

Verify the digest against the raw request bytes before parsing or re-serializing JSON, and compare signatures using a constant-time comparison. Your receiver may also use the signature timestamp in its own replay policy; do not substitute the event's JSON timestamp when calculating the digest.

Acknowledge and deduplicate deliveries

Return any 2xx status only after the receiver has durably accepted the event. Redirects and non-2xx statuses are failures, and each attempt has a 15-second timeout.

Managed delivery retries a failed event up to five attempts. Delivery is fan-out: if one active destination fails, the event is retried as a whole. A destination that already succeeded can therefore receive the same event again while another destination is recovering.

Every receiver must be idempotent. Record the event ID with the completed side effect in one durable transaction where possible, and return success for a recognized duplicate after confirming the prior work is complete.

Apply lifecycle

Selecting Save and apply performs two distinct steps:

1. Parix validates and persists the desired configuration, secrets, and destinations with queued status.
2. Parix enqueues a workflow to apply that configuration to the provider deployment.

The second step can fail after the first has succeeded. If the page reports that CDC changes were queued but the apply workflow failed, the desired configuration still exists. Check the CDC status and Cluster > Changes before editing or submitting again. Repeated submissions can obscure which desired state should be applied.

Wait for active before expecting new managed attempts. If the workflow reaches error, correct the reported configuration issue and submit one new apply request. See Observability, backups, and CDC troubleshooting for the evidence to collect.

Inspect webhook delivery history

Open the dedicated database and choose Webhooks. Delivery history can be filtered by:

• time range: last 24 hours, 7 days, or 14 days;
• status: all, success, or failed; and
• destination.

The page shows 20 entries at a time. Use Latest to return to the newest page or the cursor controls to move through older entries available to the UI.

Select an event to inspect its attempt ID and time, destination and URL, queue attempt, HTTP status, failure reason, error text, and payload preview. Failure categories include http_error, timeout, network_error, build_request_error, and egress_policy_error.

The selectable range is not a promise that every event is retained for 14 days; server-side age and row limits can remove older history. For a delivery incident, correlate the Parix event ID with receiver logs promptly.

For symptom-based recovery steps, see Observability, backups, and CDC troubleshooting.