#How do I create opportunities from an external system (webhook)?

Set up an External entry with the Webhook received trigger: the stage gets a unique URL and starts creating an opportunity whenever any system — your own form, an ERP, a Zapier/Make scenario, a script — sends a POST with JSON to it. Use it when there is no ready-made integration with the source platform.

Do not mix it up with the Outbound webhook: that one sends the opportunity data out (see how to set it up). This one receives and creates the card.

Before you start

• Workspace role: owner, admin or editor. Without one of these you cannot create or edit stage automations. See what each role covers in the permissions table.
• You need a pipeline with at least one stage. If you do not have one yet, start with Build your first pipeline.
• The caller needs to be able to send a POST with JSON — any tool that makes HTTP requests works.

#Steps

1. Open the pipeline and, on the stage that will receive the opportunities, click Create automation.
2. In the Type step, choose External entry and click Continue.
3. Under the Webhooks category, choose Webhook received.
4. Click Add entry. The URL is generated at that moment.
5. In On this stage, on the side, the new entry shows up with the URL. Click it to copy and paste it into your system.

The URL does not change when you save the automation again — you can publish it in your system without risking the integration.

#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 it finds none, it creates the contact.
• leadId — uses exactly that contact, creating nothing.

Besides the identification, the body accepts contact fields (name, document, instagram, birthday as YYYY-MM-DD, profession, city, state, address), customFields (custom fields by name) and tags (up to 20 names). The details of each field, the limits and what happens to extra keys are in How do I start an automation from an external system (webhook) — the body is exactly the same.

Example:

{
  "email": "[email protected]",
  "name": "Maria Souza",
  "telephone": "5511999998888",
  "tags": ["webhook"]
}

The opportunity is created in this stage and linked to the identified contact. The other automations on the stage — assignment, action & delay — run normally on the newly created card.

#Responses

#Repeated calls and limits

• Repeats: send the X-Idempotency-Key header (or the idempotencyKey field in the body) with an identifier of yours. Retries with the same key within 24 hours count as one call — you do not get two opportunities. If the call fails, the key is released.
• Size and pace: the body accepts up to 32 KB, and each source can send up to 300 calls per minute.

#Protect the URL

The URL is the secret — anyone holding the address can create opportunities in your pipeline. Treat it like a password and do not publish it. If you suspect it leaked, delete the entry and create another one: the old URL starts returning an error immediately.

#Related

• Notify another system when an opportunity enters a stage
• How do I start an automation from an external system (webhook)
• Build your first pipeline

#If it did not work

• Create automation does not show on the stage → your role does not allow configuring the pipeline. Check No permission and the permissions table.
• You could not find Webhook received in the list → it lives under the Webhooks category, and only appears in External entry. It is not offered in Passage trigger: the webhook creates the opportunity, it does not move an existing one.
• The call answered 202 but no card appeared → check that the automation is active on the stage. A paused automation records the call and creates the contact, but does not create the opportunity.
• Two cards were created for the same order → your system sent two calls without an idempotency key. Pass X-Idempotency-Key with an identifier of the order.
• To see the calls that arrived, click the automation card on the stage: the automation opens and the trigger shows the latest calls received, with the body sent and the result.