## Create webhooks

URL: https://docs.atlan.com/product/integrations/automation/webhooks/how-tos/create-webhooks

> Learn how to create webhooks in Atlan to receive event notifications to your endpoint and take action in real-time.

# Create webhooks

Webhooks let you monitor events in Atlan and send notifications to an endpoint of your choice. You can trigger actions right away when events happen. For example, receive notifications when a [term](https://docs.atlan.com/llms/governance/glossary/what-is-a-glossary/llms.txt) is updated, an asset is [tagged](https://docs.atlan.com/llms/governance/tags/what-are-tags/llms.txt), or a workflow completes.

**Supported event types:**
- Asset creation, deletion, and metadata update
- Custom metadata update for assets
- Tag attachment or removal from assets
- Workflow run completion (succeeded or failed)

:::info
Webhooks send payloads in a fixed format designed for programmatic consumption (for example, AWS Lambda or a microservice). If you need custom payload formatting, consider [Slack](https://docs.atlan.com/llms/governance/integrations/integrate-slack/llms.txt) or [Microsoft Teams](https://docs.atlan.com/llms/governance/integrations/integrate-microsoft-teams/llms.txt) integrations instead.
:::

## Prerequisites

Before you begin, make sure you have:

- Admin access in your Atlan workspace.
- Webhook endpoint URL ready to receive notifications.
- If behind a VPN or firewall: [add the Atlan IP to your allowlist](https://docs.atlan.com/support/submit-request).

## Create webhook

1. In your Atlan workspace, click **Settings** from the left menu.

 If you are using the **Old UI (Classic)**, from the left menu, click **Admin**.

2. Click **Webhooks**.

3. Click **+ New Webhook**.

4. Enter the following details:
 - **Name**: A meaningful name for your webhook.
 - **Webhook URL**: The endpoint where you want to receive notifications.
 - **Asset type**: The asset types to monitor (optional; defaults to all types).
 - **Event type**: Select the events you want to receive:
 - **Assets**: Create, Update, Delete, Update Custom Metadata, Add Tags, Delete Tags
 - **Workflows**: Workflow Succeeded, Workflow Failed

5. Click **Validate** to test the endpoint. Atlan sends a sample payload; respond with `2xx` status to confirm.

6. Click **Save**. You'll see your webhook's secret key in the confirmation dialog.

7. Copy the secret key to a secure location. You'll need it to [verify requests from Atlan](#verify-requests-from-atlan).

8. Click **Done**.

## Workflow event payloads

When a workflow completes, Atlan sends a JSON payload to your endpoint. Both `workflow_succeeded` and `workflow_failed` events use the same structure; the `status` field indicates the outcome.

### Example payload

```json
{
 "domain": "your-tenant.atlan.com",
 "startTime": "2026-05-12T06:00:02Z",
 "endTime": "2026-05-12T06:10:18Z",
 "runTime": 616,
 "workflowTemplate": "atlan",
 "packageName": "@atlan/your-package",
 "workflowId": "YOUR_WORKFLOW_ID",
 "runId": "YOUR_RUN_ID",
 "isSchedule": true,
 "workflowName": "your-workflow-name",
 "cronString": "*/30 * * * *",
 "nextRunInMinutes": 30,
 "failedSteps": [],
 "runningSteps": [],
 "assetsCreated": 0,
 "assetsUpdated": 0,
 "assetsDeleted": 0,
 "lastThreeRuns": ["Succeeded", "Succeeded", "Succeeded"],
 "recurringFailuresInDays": 0,
 "isFirstRun": false,
 "isEverRunSuccessfully": true,
 "status": "succeeded",
 "potentialIssues": []
}
```

### Key fields

| Field | Description |
|---|---|
| `status` | Whether the run `succeeded` or `failed`. |
| `workflowName` | Name of the workflow that ran. |
| `workflowId` | Unique identifier for the workflow. |
| `runId` | Unique identifier for this specific run. |
| `startTime` / `endTime` | ISO 8601 timestamps for the run window. |
| `runTime` | Duration of the run in seconds. |
| `failedSteps` | List of step names that failed (non-empty when `status` is `failed`). |
| `lastThreeRuns` | Status of the three most recent runs–useful for detecting recurring failures. |
| `recurringFailuresInDays` | Number of consecutive days the workflow has been failing. |
| `isSchedule` | `true` if the run was triggered by a schedule; `false` for manual runs. |

:::tip Operational alerting with workflow webhooks
Workflow webhooks are ideal for event-driven alerting. For example, trigger an AWS Lambda function to push metrics to CloudWatch or create an incident when a workflow fails. For aggregate reporting (total runs, success/failure counts), query the [Atlan Lakehouse](https://docs.atlan.com/llms/governance/lakehouse/llms.txt) for a stable SQL interface over historical run data.
:::

## Verify requests from Atlan

Atlan signs all webhooks with a unique secret. This lets you verify that requests are genuine.

Each webhook request includes an `x-atlan-signing-secret` HTTP header with the secret key you copied when creating the webhook. Use this to validate incoming requests.

## Need help?

If you have any issues while setting up webhooks, contact [**Atlan Support**](https://docs.atlan.com/support/submit-request) for assistance.

## See also

- [Microsoft Teams integration](https://docs.atlan.com/llms/governance/integrations/integrate-microsoft-teams/llms.txt)
- [Slack integration](https://docs.atlan.com/llms/governance/integrations/integrate-slack/llms.txt)

---