Skip to main content

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 is updated, an asset is tagged, 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 or Microsoft Teams integrations instead.

Prerequisites​

Before you begin, make sure you have:

Create webhook​

  1. From the left menu in Atlan, click Admin.

  2. Under Workspace, 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.

  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​

{
  "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​

FieldDescription
statusWhether the run succeeded or failed.
workflowNameName of the workflow that ran.
workflowIdUnique identifier for the workflow.
runIdUnique identifier for this specific run.
startTime / endTimeISO 8601 timestamps for the run window.
runTimeDuration of the run in seconds.
failedStepsList of step names that failed (non-empty when status is failed).
lastThreeRunsStatus of the three most recent runs–useful for detecting recurring failures.
recurringFailuresInDaysNumber of consecutive days the workflow has been failing.
isScheduletrue if the run was triggered by a schedule; false for manual runs.
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 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 for assistance.

See also​