> For the complete documentation index, see [llms.txt](https://docs.notionapps.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.notionapps.com/automation/webhooks-and-integrations.md).

# Webhooks and Integrations

Use webhooks and integrations when automation needs to communicate outside the current app. This can mean receiving work from an external system, sending an approved record to another system, handing work to another NotionApps app, or waiting for Make so the **already-open tab** can refresh.

Use Linked App Exchange when work moves between apps.

{% hint style="info" %}
**Workflow webhooks and Messaging webhooks are different products.** They share one **per-app webhook secret**, but use different URLs and jobs. Generate the secret in the Workflow builder, then choose a path in [Workflow vs Messaging Webhooks](https://docs.notionapps.com/automation/webhooks-and-integrations/workflow-vs-messaging-webhooks).
{% endhint %}

**Create a webhook secret first**

1. Open **Automation → Workflows**.
2. Use a workflow whose trigger is **Webhook received**.
3. In **External webhook intake**, name the secret (for example `Make production`) and pick a term: 30, 90, 180, or 365 days, or no expiry.
4. Click **Generate secret** and copy the value immediately. It is not shown again.
5. In Make or Zapier, send `x-notionapps-webhook-token: {secret}`.

After this app has an active secret, the old shared platform token stops working for it. You can keep up to five active secrets so you can rotate without downtime. Full steps: [Webhook Technical Reference](https://docs.notionapps.com/automation/webhooks-and-integrations/webhook-technical-reference).

**When to use external automation**

Use a webhook or linked app handoff when:

* A form outside NotionApps should create a record.
* An approved request should notify another system.
* A customer app should send work to an internal operations app.
* A completed workflow should update another tool.
* A failed external delivery should create an exception.
* A button must call Make, then Refresh or Open screen on the **same open tab**.

**Two outbound webhook steps**

| Step                           | Behavior                                                                                                                                  | Use when                                                                                               |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Notify** (channel = Webhook) | Fire-and-forget POST. The run continues in the background.                                                                                | Another system should hear the result. The open tab does not need to wait.                             |
| **Call webhook and wait**      | POST, wait up to 8 seconds (max 12s) for a JSON **Webhook response**, then continue Refresh / Open screen / Show message on the same tab. | Request Revision, “build the cart,” or any button that must wait for Make before the open tab updates. |

Do not use Notify webhook when the open tab must update after Make. Inbound webhooks Make fires back at NotionApps still cannot refresh an already-open tab.

{% hint style="info" %}
**Live screen updates** must be on for the app, or Refresh after Call webhook and wait / Update will not update the open tab. The switch is off by default. NotionApps turns it on from Workflow Operations → Controls. See the [Step catalog](https://docs.notionapps.com/automation/advanced-reference/step-catalog).
{% endhint %}

**Maker setup pattern**

1. Generate a webhook secret and store it in Make/Zapier.
2. Decide the event that should send or receive data.
3. Choose the source record.
4. Map only the fields the destination needs.
5. Define success status.
6. Define failure status.
7. Show delivery result in Workflow Status, Linked App Exchange, or Exception Resolution.
8. If the open tab must update after Make: use **Call webhook and wait**, and end the Make scenario with **Webhook response** JSON.
9. Test with realistic data.
10. Confirm no secrets are exposed to app users.

**Call webhook and wait (Make)**

1. Add **Call webhook and wait** and paste the Make webhook URL.
2. Leave the sync timeout at 8000 ms unless you need a shorter wait (max 12 seconds on the tap).
3. In Make, end with **Webhook response** and return JSON, for example `{ "ok": true, "cart_record_id": "…" }`.
4. Map later Open screen record id to `context.<this_step_id>.cart_record_id` when Make returns one.
5. Follow with Refresh / Open screen / Show message.

What the user sees:

* Make answers within 8 seconds: the following UI steps run on the open tab.
* Make is still going: Working… then the app polls the run for 45 seconds.
* Still pending: “This is taking longer. Refresh to see the cart.”
* 4xx / 5xx in the sync window: error, no refresh, no retry.

Full HTTP shapes, secrets, and inbound testing: [Webhook Technical Reference](https://docs.notionapps.com/automation/webhooks-and-integrations/webhook-technical-reference).

**Verification**

External automation is ready when the sending app shows success, the receiving system has the expected data, and failed delivery creates a visible exception.

Call webhook and wait is ready when a button tap either updates the open tab from Make’s JSON, or shows Working… / the fallback refresh message — not a silent no-op.