#How do I start an automation from an external system (webhook)?

Use the Webhook received trigger (in the Webhooks category): the automation gets a unique URL and starts whenever any system — your own form, an ERP, Zapier/Make, a script — sends a POST request with JSON to that URL. No native integration with the source platform is required.

Role: any member with access to the workspace.

#Step by step

1. On the automation canvas, add (or change) the trigger and pick Webhook received, in the Webhooks category.
2. The configuration panel opens with the Webhook URL already created for this automation. Click Copy and paste it into your external system.
3. Before activating, use Test payload: paste a sample JSON and click Test. You see how it would be interpreted — which contact would be used (or created) and which variables would become available — without saving anything or starting the automation.
4. Click Save and activate the automation.
5. Send a real POST request and check Latest received calls (in the same panel) to confirm it arrived and with which result.

#What to send in the POST body

The body must be a JSON object and identify the contact in at least one of these ways:

• email and/or telephone — the platform looks for an existing contact (deduplication by email and phone). If none is found, the contact is created.
• leadId — uses exactly that contact, without creating anything.

Besides identification, the payload accepts:

• Contact fields: name, document, instagram, birthday (YYYY-MM-DD), profession, city, state, address — they fill the new contact, or complete empty fields on an existing contact (they never overwrite what is already filled).
• customFields: object with the contact's custom fields, referenced by name (e.g. { "customFields": { "Plan": "Pro" } }).
• tags: list of up to 20 tag names to apply to the contact (tags that do not exist yet are created).
• kind: reserved. Today it only accepts "lead" (it can be omitted); any other value makes the call be rejected.
• Any other key becomes an execution variable: a payload with "source": "my-erp" makes {{source}} available in messages, HTTP requests and conditions of the next steps. Up to 100 keys per call, with names of up to 128 characters.

Some keys are reserved by the automation (leadId, ownerId, flowId, cardId, offerId, tags, customFields, among others used internally) and do not become variables. If your system uses one of those names, rename the field — the Test payload tool lists everything that was ignored.

Example:

{
  "email": "contact@example.com",
  "name": "Maria Souza",
  "customFields": { "Plan": "Pro" },
  "tags": ["webhook"],
  "source": "my-erp",
  "cartValue": 149.9
}

#Responses

#Security, limits and retries

• The URL is the secret. Treat it like a password. If it leaks, click Rotate URL in the trigger panel: a new URL is generated instantly and the old one starts returning an error — no need to recreate the automation.
• Limits: the body accepts up to 32 KB, and each source can send up to 300 calls per minute.
• Repeated calls: send the X-Idempotency-Key header (or the idempotencyKey body field) with your own identifier. Resends with the same key within 24 hours count as one call — the automation does not start twice. If the call fails, the key is released: resending after fixing it works normally.
• Even without an idempotency key, the automation respects its configured minimum interval between executions for the same contact (1 hour by default).

#Debugging an integration

The trigger panel shows the latest received calls, with the sent payload and the result:

The list does not refresh on its own — click Refresh after sending the POST.

To check what each payload key became inside the automation, open the run on the Executions tab and see the data and variables of that run.

If a call shows as Accepted but the automation does not run, check:

• whether the automation is active — in a paused or draft automation the contact is still created and the call is logged, but no execution starts;
• whether the same contact already started this automation within its configured minimum interval (1 hour by default).

One detail about email: it is compared exactly as sent. If your system sends Maria@Example.com and the contact was created as maria@example.com, they become two different contacts — normalise the casing on your side.