Configure a webhook

Map incoming JSON payloads to table rows, with optional HMAC signature verification.

PUT /v1/tenants/{tenant}/webhooks/{hook_id}

Define how deliveries become table rowsWithout a signature block, the hook accepts unsigned deliveries.

Prepare the destination tableRegister the schema before configuring the hook.
Map payload fieldsConnect JSON paths to destination columns.
Save verification settingsConfigure signing when needed; send only the secret setting's name.

Before you start

Use your database bearer token.

Register the destination table first. For the signed example, configure OC_DOCS_WEBHOOK_SECRET on the server and send only its setting name.

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

schema is the destination table id (namespace.table) and must already exist.
field_mapping maps each destination column name to a JSONPath-style expression (e.g. $.event.id, $.items[0].id) and must have at least one entry.
Without a signature block the hook accepts unsigned deliveries.

Field	Type	Required	Description
`array_path`	`string`	Optional	—
`field_mapping`	`object`	Required	—
`idempotency_key_path`	`string`	Optional	—
`schema`	`string`	Required	—
`signature`	`object`	Optional	format is one of: hex_sha256 (default), stripe_t1. secret_env_var is the NAME of a setting on the database server that holds the shared secret; the secret value itself is never sent or returned.

Fields in signature

Field	Type	Required
`format`	`string`	Optional
`header`	`string`	Required
`secret_env_var`	`string`	Required

The response is the saved mapping configuration. field_mapping maps destination columns to payload paths. Without a signature block, the hook accepts unsigned deliveries; choose that behavior deliberately.

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.
503	Honor Retry-After when present; check write outcomes.

Request example

curl --include --request PUT "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/webhooks/demo-people" \
  --header "Authorization: Bearer ${OC_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary '{
  "schema": "demo.people",
  "field_mapping": {
    "id": "$.event.id",
    "follows_id": "$.event.follows_id",
    "score": "$.event.score"
  },
  "idempotency_key_path": "$.delivery_id",
  "signature": {
    "header": "X-Docs-Signature",
    "secret_env_var": "OC_DOCS_WEBHOOK_SECRET",
    "format": "hex_sha256"
  }
}'

Response example

Examples use synthetic values to show the response format.

Response status

{
  "schema": "demo.people",
  "field_mapping": {
    "id": "$.event.id",
    "follows_id": "$.event.follows_id",
    "score": "$.event.score"
  },
  "idempotency_key_path": "$.delivery_id",
  "signature": {
    "header": "X-Docs-Signature",
    "secret_env_var": "OC_DOCS_WEBHOOK_SECRET",
    "format": "hex_sha256"
  }
}

Download the OpenAPI specification for the complete response schemas.

Before you startCopy Anchor Link

Path parametersCopy Anchor Link

HeadersCopy Anchor Link

Request bodyCopy Anchor Link

Read the resultCopy Anchor Link

Response statusesCopy Anchor Link

Before you start

Path parameters

Headers

Request body

Read the result

Response statuses