Database endpoints
Receive a webhook delivery
Verify a webhook delivery and write its mapped rows.
POST /v1/tenants/{tenant}/webhooks/{hook_id}
- Send the original payloadUse the configured hook and required signature header.
- Verify and map its fieldsApply the saved signature and column mappings.
- Inspect rows_ingestedHandle missing parent records according to the returned retry guidance.
Before you start
Use your database bearer token.
Create the hook first. For this signed example, add X-Docs-Signature as the hex HMAC-SHA256 of the exact body bytes; the example does not include a signature value.
Path parameters
| Field | Type | Required |
|---|---|---|
tenant | string | Required |
hook_id | string | Required |
Headers
| Field | Type | Required | Description |
|---|---|---|---|
x-oc-db-user | string | Optional | Acting database user (role, grant and row-policy checks). Send with x-oc-db-key. |
x-oc-db-key | string | Optional | API key of the x-oc-db-user user. |
Request body
application/json
Limits and accepted values
- Arbitrary JSON payload from the sending service (read as raw bytes and parsed as JSON;
- Content-Type is not checked).
- With array_path set, the value at that path must be an array (or null = zero rows);
- otherwise the whole payload is one record.
- Signature header value: hex_sha256 = hex of HMAC-SHA256(secret, body);
- stripe_t1 = 't=<unix>,v1=<hex>' over '<t>.<body>'.
- A mapped row naming a missing foreign-key parent is refused with 503 + Retry-After: 5 so the sender redelivers.
| Field | Type | Required | Description |
|---|---|---|---|
Fields | object | Optional | Arbitrary JSON payload from the sending service (read as raw bytes and parsed as JSON; Content-Type is not checked). With array_path set, the value at that path must be an array (or null = zero rows); otherwise the whole payload is one record. Signature header value: hex_sha256 = hex of HMAC-SHA256(secret, body); stripe_t1 = 't=<unix>,v1=<hex>' over '<t>.<body>'. A mapped row naming a missing foreign-key parent is refused with 503 + Retry-After: 5 so the sender redelivers. Receives a delivery for a registered webhook: when the hook has a signature block, the request must carry an HMAC-SHA256 signature of the raw body in the configured header (a missing or invalid signature returns 401), the JSON payload is mapped through the hook's field mapping, and the resulting rows are written to the destination table; the request also passes the standard bearer-token check. |
Read the result
rows_ingested reports mapped rows accepted from this delivery. For a signed hook, calculate the signature over the exact raw body bytes. A foreign-key parent missing at delivery time can return 503 with a retry delay.
Response statuses
HTTP status reference
| Status | What to do |
|---|---|
| 200 | OK |
| 400 | Correct the request before retrying. |
| 401 | Check the credential and Authorization header. |
| 402 | Check feature access or available credits. |
| 403 | Check tenant access, roles and permissions. |
| 404 | Check the resource ID and API route. |
| 413 | Split or reduce the request body. |
| 415 | Send the required Content-Type. |
| 422 | Correct the values or unsupported combination. |
| 429 | Honor Retry-After when present; back off. |
| 500 | Check the outcome before retrying a write. |
| 501 | Check deployment support for this operation. |
| 503 | Honor Retry-After when present; check write outcomes. |