POST

Custom Event Trigger

Fires when your application posts a custom event to the inbound webhook.

POSThttps://api.vantaxai.com/v1/workflows (trigger: custom.event)

Use the `custom.event` trigger to start a Workflow from your own systems. POST any JSON body to your sub-account's inbound webhook (`/v1/workflows/webhook/{sub_account_id}`) and set `trigger.config.event_name` to match the `name` you send. The entire posted payload is delivered to the Workflow as the `trigger_event` shown below. Reference this trigger by setting `trigger.type` to `custom.event` on the Create Workflow endpoint.

Inbound webhook

Send custom events to https://api.vantaxai.com/v1/workflows/webhook/{sub_account_id}. The endpoint returns 200 immediately and dispatches matching Workflows asynchronously.

Headers

Authorizationstringrequired
Bearer authentication with your secret API key.
example: Bearer vx_live_3fa9c2…
Content-Typestringrequired
Must be application/json for requests with a body.
example: application/json

Body Parameters

trigger.typestringrequired
Set to `custom.event` to use this trigger.
example: custom.event
trigger.config.event_namestringrequired
The custom event name to match against the inbound webhook payload's `name`.
example: invoice.paid

Request

curl -X POST https://api.vantaxai.com/v1/workflows (trigger: custom.event) \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
  "trigger.type": "custom.event",
  "trigger.config.event_name": "invoice.paid"
}'

const res = await fetch(
  "https://api.vantaxai.com/v1/workflows (trigger: custom.event)",
  {
  method: "POST",
  headers: {
    Authorization: "Bearer vx_live_3fa9c2...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "trigger.type": "custom.event",
    "trigger.config.event_name": "invoice.paid"
  }),
  }
);
const { data } = await res.json();

import { Vantax } from "@vantax/sdk";

const vantax = new Vantax({ apiKey: process.env.VANTAX_API_KEY! });
// POST /v1/workflows (trigger: custom.event)
const result = await vantax.request("POST", "/v1/workflows (trigger: custom.event)", {
  "trigger.type": "custom.event",
  "trigger.config.event_name": "invoice.paid"
});

from vantax import Vantax

vantax = Vantax(api_key=os.environ["VANTAX_API_KEY"])
# POST /v1/workflows (trigger: custom.event)
result = vantax.request("POST", "/v1/workflows (trigger: custom.event)", json={"trigger.type": "custom.event", "trigger.config.event_name": "invoice.paid"})

Response

{
  "type": "custom.event",
  "occurred_at": "2026-02-02T12:00:00Z",
  "sub_account_id": "sub_8a1f4c2e",
  "data": {
    "name": "invoice.paid",
    "contact_id": "ct_91ad22",
    "payload": {
      "invoice_id": "inv_4471",
      "amount": 250.00,
      "currency": "usd"
    }
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    { "field": "trigger.config.event_name", "message": "event_name is required for custom.event triggers" }
  ]
}