Webhooks

A webhook is a standing instruction: when this event happens in my workspace, POST it to my URL. You register the URL once, Custral signs and delivers every matching event, and your endpoint runs on your own infrastructure.

POST https://api.yourapp.com/hooks/custral
X-Custral-Event: record.updated
X-Custral-Signature: t=1789412334,v1=4f3c9a…
Content-Type: application/json

{
  "id": "whd_3JAx8Qm2r",
  "event": "record.updated",
  "createdAt": "2026-09-11T14:18:54.201Z",
  "data": {
    "recordId": "rec_3Ab9xK2mQ7",
    "objectId": "obj_2Zc7pL",
    "propertyId": "prop_5Nd3kR",
    "previous": ["opt_qualified"],
    "current": ["opt_negotiation"],
    "record": {"name": "Ravenna Foods", "stage": ["opt_negotiation"]}
  }
}

When to reach for one

You want to be told when something changes, and you own a server that can receive an HTTP request.

The API

You want a snapshot right now, or you are catching up after downtime.

Workflows

The reaction lives inside Custral: send an email, create a task, move a stage. No endpoint to run.

Webhooks and workflows are not rivals. A workflow is the right tool when the whole reaction happens in the workspace; a webhook is the right tool when your own system has to know.

How a delivery works

An event fires

Somebody creates a record, submits a form, completes a task. Custral emits a domain event, which you can also browse under Settings → Events.

Custral matches your subscriptions

Every active subscription in the workspace whose event list matches is selected. One event can fan out to several endpoints.

A delivery is recorded, then queued

Each match gets a whd_… delivery row before anything leaves the building, so a delivery survives a worker restart.

Custral POSTs it, signed

The body is signed with your endpoint’s secret and sent with a 10 second timeout. Any 2xx is success. Anything else is retried.

Nineteen events across records, forms, tasks, email, the chat widget and conversations, and every one of them actually emits.

Resource	Events
Records	`record.created`, `record.updated`, `record.deleted`
Forms	`form.submitted`
Tasks	`task.completed`
Email	`email.received`, `email.replied`, `email.sent`, `email.opened`, `email.clicked`, `email.bounced`, `email.unsubscribed`
Widget	`widget.conversation.started`, `widget.visitor.identified`, `widget.keyword.matched`
Conversations	`conversation.assigned`, `conversation.completed`, `conversation.deleted`, `conversation.outcome_set`

You can also subscribe with * for everything, or a prefix glob like record.*. See the event catalog for when each one fires and the exact payload it carries.

If an event you want is not on that list, tell us which one at hello@custral.com.

Getting started

Building a receiver

Event reference

Operations

Webhooks

When to reach for one

Webhooks

The API

Workflows

How a delivery works

Start here

Quickstart

Payload format

Verify signatures

Delivery and retries

​When to reach for one

Webhooks

The API

Workflows

​How a delivery works

​What you can subscribe to

​Start here

Quickstart

Payload format

Verify signatures

Delivery and retries

When to reach for one

How a delivery works

What you can subscribe to

Start here