Webhooks

Add webhooks to a table to fire outgoing HTTP POST requests when records are created, updated, or deleted. Each webhook is syntactic sugar over automations — internally it expands to a record trigger plus a webhook.send action. Webhook names must be unique within the table.

Webhook Properties

Property	Description
`name`	Required. Unique webhook identifier within the table.
`url`	Required. Destination URL. Must be a valid absolute `http(s)` URL.
`events`	Required. Record events that trigger delivery: any of `create`, `update`, `delete` (at least one).
`enabled`	Boolean. Whether the webhook is active (default `true`).
`auth`	Authentication for the outgoing request (HMAC, API key, or bearer). See below.
`retry`	Retry policy for failed deliveries. See below.
`payload`	Payload field selection and metadata options. See below.

app.yaml

webhooks:
  - name: order_created
    url: https://hooks.example.com/orders
    events: [create]
    enabled: true

Authentication

auth secures the request. Three types are supported; secrets/keys/tokens support $env. references.

Type	Properties
`hmac`	`secret` (required), `algorithm` (`sha256` default, or `sha1`), `header` (signature header name).
`apiKey`	`key` (required), `header` (header name to carry the key).
`bearer`	`token` (required) sent as a bearer token.

app.yaml

auth: { type: hmac, secret: '$env.PARTNER_WEBHOOK_SECRET', algorithm: sha256 }

app.yaml

auth: { type: apiKey, key: '$env.SERVICE_API_KEY', header: X-API-Key }

app.yaml

auth: { type: bearer, token: '$env.API_BEARER_TOKEN' }

Retry Policy

retry controls how failed deliveries are retried.

Property	Description
`maxAttempts`	Number of retry attempts after the initial failure. `0` disables retries. Default `3`.
`backoff`	Backoff strategy: `exponential` or `fixed`.
`initialDelay`	Milliseconds before the first retry (default `1000`).
`maxDelay`	Maximum delay in milliseconds between retries.

app.yaml

retry: { maxAttempts: 5, backoff: exponential, initialDelay: 1000, maxDelay: 300000 }

Payload Selection

payload shapes what data is sent. includeFields (whitelist) and excludeFields (blacklist) are mutually exclusive, and every named field must exist on the table (the implicit id is always valid).

Property	Description
`includeFields`	Only include these fields (whitelist).
`excludeFields`	Exclude these fields (blacklist).
`includePreviousValues`	Include the record's previous values on `update` events.
`includeMetadata`	Include event metadata in the payload.

app.yaml

payload: { includeFields: [customer, status, total], includePreviousValues: true }

Full Example

app.yaml

webhooks:
  - name: order_lifecycle
    url: https://hooks.example.com/orders
    events: [create, update, delete]
    enabled: true
    auth: { type: hmac, secret: '$env.ORDER_WEBHOOK_SECRET', algorithm: sha256 }
    retry: { maxAttempts: 5, backoff: exponential, initialDelay: 1000, maxDelay: 300000 }
    payload: { excludeFields: [internal_notes], includePreviousValues: true }

Validation. Webhook names must be unique within a table, and any field referenced by payload.includeFields / excludeFields must name a real field (or the implicit id). Invalid URLs and non-http(s) schemes are rejected at config-decode time.

Last updated August 11, 2026

← PreviousPermissions Next →Field Types

Edit this page Report an issue

This documentation was written with AI, so errors or outdated content are possible. Sovrium is in beta. Contributions and corrections are welcome.