APIs, integrations & migration

Outbound webhooks

Lets an external system learn that a record was written, by receiving a signed HTTP POST from KynetraDB.

BetaEngine edition 5f8ea3af

What it does

An administrator registers a URL, a list of event names and a signing secret. When a record is created through the native entity endpoint or the collection record endpoint, KynetraDB posts a JSON event to each matching active subscription with an HMAC-SHA-256 signature header, and keeps a short delivery log. Delivery is a single attempt per event: there are no retries, and several write paths raise no event.

How it works

Subscriptions are managed under /admin/webhooks by an administrator: list, create, delete, send a test event, and read the delivery history of one subscription. A subscription holds a URL, event names (an empty list or * matches every event), a secret and an active flag. If no secret is supplied the server generates a random 32-byte hexadecimal secret. Subscriptions are kept in a JSON file in the data directory and apply to the whole instance, not to one project.

On a matching write the server hands the delivery to a background task, so the write is not delayed. The body is a JSON object with the event name, the entity as data and a timestamp. The request carries X-Kynetra-Signature, the hexadecimal HMAC-SHA-256 of the raw body keyed with the subscription secret, and X-Kynetra-Event. A receiver should verify the signature over the raw bytes before it parses the body. The HTTP client gives up after ten seconds.

Each attempt appends a record to a delivery log: the status code, or zero with an error message when the request failed. The log keeps the newest 50 deliveries across all subscriptions and is stored in a JSON file beside the subscriptions. A test delivery runs inline and returns the receiver status in the response.

The one event name the server raises is record.created. It is raised when an entity is written through POST /v1/entities, including a write that overwrites an existing id, and when a record is created through POST /v1/collections/{name}/records.

Where you reach it

  • HTTPGET /admin/webhooks, POST /admin/webhooks
  • HTTPDELETE /admin/webhooks/:id
  • HTTPPOST /admin/webhooks/:id/test
  • HTTPGET /admin/webhooks/:id/deliveries

Example

Subscribe a receiver to created recordsbash
curl -s -X POST "$BASE/admin/webhooks" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/kynetra","events":["record.created"]}'

Limits

  • One attempt per event. A failed or timed-out delivery is written to the log and not retried, so a receiver that is down misses events. Make the receiver idempotent, and reconcile through the change feed when you need completeness.
  • The server raises one event name, record.created, from the two endpoints above. Updates and deletes through the collection record endpoints, writes through the REST layer, transactions and bulk imports raise no webhook event.
  • The delivery log holds the newest 50 deliveries across all subscriptions.
  • Subscriptions apply to the whole deployment; configure them as an operator. Restrict access to the data directory, because it holds the subscription secrets.
  • The signature covers the body. The timestamp travels inside the body, so a receiver that needs replay protection has to check it.
  • No automated test in the engine repository covers the subscription store or the delivery code. Test your receiver before you rely on it.

Evidence

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to talk through the limits above against your own workload.