Webhooks

Webhooks connect Bento workflows to the rest of your stack. Use a workflow Send webhook action when Bento should notify another system, such as a CRM, fulfillment tool, internal app, or support queue.

If another system needs to send data into Bento, use the Events API. That keeps inbound data in the same event model that powers segments, workflows, and reporting.

Bento does not currently expose account-level outbound event subscriptions in these docs. This page covers the workflow Send webhook action and inbound event tracking through /batch/events.

Available Patterns

MethodEndpoint

POSTWorkflow action: Send webhook

Send data out

Call your endpoint from a Bento workflow step.

POST/batch/events

Send data in

Track external events in Bento and trigger automation.

Send Webhooks From Workflows

Add Send webhook when a workflow reaches the point where an external system should act. Common examples include:

Sending a high-intent lead to your CRM.
Creating a fulfillment task after a purchase event.
Posting a trial conversion to an internal reporting service.
Notifying your app that Bento added or removed a lifecycle tag.

Configure the action with the destination URL and the JSON body your app expects. Use Liquid variables when the payload needs data from the person, event, site, or workflow context.

Use a workflow webhook for actions that should happen because a person reached a specific step. Use the Events API for external systems that need to create events in Bento.

Action Fields

Name
url
Type
string
Description
The public HTTPS endpoint Bento should call.
Name
method
Type
string
Description
Use POST unless your endpoint explicitly expects another method.
Name
body
Type
object
Description
JSON payload sent to your endpoint. Build this from static values and Liquid variables.
Name
headers
Type
object
Description
Optional request headers your endpoint needs, such as a shared secret.

Example payload

POST

Workflow action: Send webhook

{
  "event": "bento.workflow.step_reached",
  "workflow": "{{ workflow.name }}",
  "email": "{{ visitor.email }}",
  "person": {
    "first_name": "{{ visitor.first_name }}",
    "tags": "{{ visitor.tags }}"
  },
  "source_event": {
    "type": "{{ event.type }}",
    "details": {{ event.details | json }}
  }
}

Receive Events In Bento

When a third-party system sends data to you first, forward the important event to Bento through /batch/events.

POST

/v1/batch/events

curl -X POST 'https://app.bentonow.com/api/v1/batch/events?site_uuid=YOUR_SITE_UUID' \
  -u 'PUBLISHABLE_KEY:SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{
    "events": [{
      "type": "crm.deal_won",
      "email": "customer@example.com",
      "fields": {
        "plan": "growth",
        "customer": true
      },
      "details": {
        "deal_id": "deal_123",
        "value": {
          "currency": "USD",
          "amount": 3000
        }
      }
    }]
  }'

Events can create new people, update fields, and trigger workflows. For the full request shape, see the Events API reference.

Payload Design

Good webhook payloads are boring and predictable. Keep the top-level keys stable, put nested business data under details, and include an id from your system when the action can run more than once.

Name
event
Type
string
Description
A stable name for the action, such as bento.workflow.step_reached.
Name
email
Type
string
Description
The person this workflow step is about. Use the email as the lookup key in most external systems.
Name
workflow
Type
string
Description
The workflow or step name that sent the webhook.
Name
details
Type
object
Description
Extra data your app needs. Keep it JSON serializable.
Name
external_id
Type
string
Description
Optional id from your app or CRM. Use it to make your receiver idempotent.

Testing And Debugging

Start with a test workflow and a seed contact you control.
Use a service like webhook.site to inspect the first payload before pointing Bento at production.
Return a 2xx status quickly. Do slow work in your own queue after receiving the request.
Log the request body, response status, and your own correlation id.
If a workflow webhook does not arrive, check that the workflow is active, the person reached the step, the URL is public, and the endpoint accepts JSON.

Security Checklist

Use HTTPS for every destination URL.
Add a shared secret header and reject requests without it.
Treat all incoming webhook JSON as untrusted input.
Avoid sending API keys, passwords, or payment data in the payload.
Make your receiver safe to run twice. Network retries and manual replays can happen in any webhook system.

Workflows for the automation model.
Events API for sending inbound events to Bento.
API authentication for REST API credentials.
Troubleshooting for common integration checks.