Webhooks
Inbound only. There is no outbound event feed yet — poll instead.
There are no outbound webhooks. OmniPM does not currently POST events to a URL you register. If you need to know when something changes, poll — see Watching for changes below.
Everything on this page is inbound: an external service, or your own integration, pushing data into the platform.
How inbound endpoints authenticate
Two different mechanisms, and which one applies depends on who is calling.
Provider webhooks: signature verification
Endpoints that receive events from a third-party provider — payments, e-signature, messaging channels — verify the provider's own signature over the raw request body, against the secret held for that workspace.
Messaging endpoints are addressed per workspace, so the URL identifies whose credentials to verify against:
POST /api/webhooks/line/{workspace}
POST /api/webhooks/whatsapp/{workspace}You configure these URLs in the provider's own console when connecting the channel. A request whose signature does not verify against that workspace's secret is rejected — a valid signature for a different workspace is not accepted.
Signature verification is over the raw bytes of the body. If something sits between the provider and the platform and re-serialises JSON — a proxy, a middleware, a logging layer — verification fails even though the payload looks identical. This is the usual cause of a webhook that works in testing and fails in production.
Your own integration: a scoped bearer token
Where you are the one pushing data in, the endpoint uses the same bearer-token auth as the rest of this API rather than a signature.
The relayed-OTA-message endpoint works this way:
POST /api/webhooks/ota-messages
Authorization: Bearer <key with ota:ingest>The key names the workspace. That is the whole point of using a token here: ingest runs scoped to the workspace that owns the key, rather than inferring an owner from the payload — which would be a guess, and a guess that puts one workspace's guest messages in another's inbox.
ota:ingest is one of the scopes the legacy shared key is explicitly denied. See
Authentication.
Watching for changes
Until an outbound event feed exists, poll the read endpoints:
- Poll on a sensible interval, not continuously. Budgets are per key and
default to 300 requests an hour — see Errors for the
429behaviour. - Pull wide, not often. Properties allows up to 500 records per request precisely so a sync can take the whole catalogue in one call rather than spending its budget on pagination.
- Use a dedicated key for the sync, so its polling cannot exhaust the budget of an interactive integration.
Delivery expectations
For provider webhooks, assume at-least-once delivery: a provider may retry, and the same event can arrive twice. Handlers on this side are written to tolerate that, but if you are building something that consumes the effects, do not assume exactly-once.
Related: Authentication, Errors.