> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://support.atomicwork.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://support.atomicwork.com/_mcp/server.

# External webhook workflows

> Start a workflow the moment another app calls an Atomicwork webhook URL

Your other tools already know when something important happens. External webhook workflows let them tell Atomicwork. A monitoring tool raises an alert, an HR system hires someone, a CI pipeline fails, and a workflow starts in Atomicwork right away, using the data the app sent.

Each external webhook workflow gets its own URL. Any app that can send an HTTP request can call it. There is no request, user, or asset needed to start the workflow. The incoming payload is the trigger.

With external webhook workflows, you can:

* **Turn alerts into incidents** – Create an urgent request when your monitoring tool reports a critical alert.

* **Sync events from other systems** – Start onboarding when your HRIS posts a new hire, or update an asset when your MDM reports a change.

* **Reply to the caller** – Send back a status code and a JSON body so the calling app knows the event was received.

> **Note**
>
> External webhook workflows **receive** calls from other apps. To **send** a request from a workflow to another app, use [HTTP requests](https://support.atomicwork.com/documentation/enterprise-workflows/actions-and-integrations/http-requests) instead.

## Creating an external webhook workflow

### Find the Webhooks category

* Go to **Automations** and select **Event-based** in the Workflow library.

* In the object list, select **Webhooks**. External webhook workflows are organization-wide, so they are listed under **Organization**.

![Webhooks category in the Event-based workflow library](/_fern-files/_img/33f18a62f4eea96125f8f21f5a0103cafdfdb0911af243d1512c83a6fdbfaa52.webp)

### Describe the workflow to AI Assist

* Click **New**. AI Assist opens with the **Event-based webhook workflows** context already selected.

* Describe what should happen when the webhook is called. Name the fields you expect in the payload, so AI Assist can use them. For example:

  > When our monitoring tool posts an alert with `alert_id`, `severity`, `service`, and `summary`, ignore `info` alerts. For `warning` and `critical` alerts, create an incident in IT Support with the summary as the subject. If an open request already exists for the same `alert_id`, add a note to it instead.

* AI Assist builds the workflow and saves it as a draft. See [Build workflows with AI Assist](https://support.atomicwork.com/documentation/enterprise-workflows/workflow-foundations/build-workflows-with-ai-assist) for tips on writing prompts.

![Creating a webhook workflow with AI Assist](/_fern-files/_img/3fdba2f38d3e8ed6ef39ecd29c9ed8a3159c73e88d8d0faa8681d14313298f20.webp)

The draft opens in the **Builder**. The first step is always the **When the webhook is called** trigger, followed by the steps that AI Assist created.

![External webhook workflow in the Builder](/_fern-files/_img/1cf0f2cf41b3deadbe2faf088636549b8a5606de1c643aca053cf8ef2e9229ff.webp)

## Configuring the webhook

Click the **When the webhook is called** trigger to open the **External webhook** panel.

### Copy the webhook URL

The webhook URL is generated once the workflow is saved. It has this format:

```
https://<your-tenant>.atomicwork.com/api/v1/external/webhook/<webhook-id>/execute
```

Click **Copy** and paste the URL into the webhook or notification settings of your external app. The URL accepts `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` requests. Send JSON payloads in the request body.

> **Warning**
>
> Treat the webhook URL like a password. Anyone who has the URL can start the workflow. Share it only with the app that needs to call it.

### Configure the HTTP response

Under **Configure HTTP response**, choose what Atomicwork returns to the caller when the webhook triggers successfully:

* **Status code** – Pick a `2xx` status code, such as `200 OK` or `202 Accepted`.

* **Response body** – Enter the JSON that the caller receives, for example `{ "received": true }`.

The workflow runs in the background after Atomicwork replies, so the response tells the caller that the event was accepted, not that every step finished.

![External webhook panel with the webhook URL and HTTP response](/_fern-files/_img/6a03754890a89f7b8c3194684d8df6845b145c64d3f3ba31b337fc5a634c172b.webp)

### Set up placeholders from a sample payload

Placeholders let later steps use values from the incoming call. To set them up, send a real sample to the webhook first.

* Call the webhook URL from your app, or with a tool such as `curl`:

  ```bash
  curl -X POST "https://<your-tenant>.atomicwork.com/api/v1/external/webhook/<webhook-id>/execute" \
    -H "Content-Type: application/json" \
    -d '{"alert_id": "ALR-1042", "severity": "critical", "service": "payments-api", "summary": "p95 latency above 2s"}'
  ```

* Open **Setup placeholders** and click **Fetch payload**. Atomicwork shows the latest 3 payloads it received.

* Choose the payload that matches what your app sends. Atomicwork lists the fields it found and their types. Click **Open in editor** to adjust the payload structure by hand.

![Setup placeholders showing fields from a received payload](/_fern-files/_img/579331f57f7fc3ed59729f701b10661da983abb701a7397cf04d583a41fc81ac.webp)

You can send sample payloads while the workflow is still a draft. A draft does not run any steps: Atomicwork stores the payload and replies with `204 No Content`.

### Use webhook data in your steps

Values from the incoming call are available under the `event` placeholder:

| Placeholder                | Contains                                                                  |
| -------------------------- | ------------------------------------------------------------------------- |
| `{{event.body.<field>}}`   | A field from the JSON request body, for example `{{event.body.severity}}` |
| `{{event.body}}`           | The whole request body                                                    |
| `{{event.query.<name>}}`   | A query string parameter, for example `?source=datadog`                   |
| `{{event.headers.<name>}}` | A request header                                                          |
| `{{event.path.<name>}}`    | A path parameter                                                          |
| `{{event.account_url}}`    | Your Atomicwork account URL                                               |

## Publishing the workflow

* Review the steps in the **Builder**. You can ask AI Assist to change the workflow, or click the code icon to see the steps as code.

* Click **Publish**.

Once the workflow is published, every call to the webhook URL starts a new run, and the caller receives the status code and body you configured. Check the runs of the workflow to confirm that each call was processed.

## Response codes

| Code                      | When it is returned                                                                                       |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| The configured `2xx` code | The workflow is published and the call was accepted.                                                      |
| `204 No Content`          | The workflow has no published version yet. The payload is stored for placeholder setup, but no steps run. |
| `404 Not Found`           | The webhook URL does not exist, or its workflow was deleted.                                              |