Webhook API - EasyAlert

Overview

The Webhook API allows external systems to trigger EasyAlert workflows via HTTP POST requests. Use it to integrate with CI/CD pipelines, monitoring tools, custom scripts, or any system that can make HTTP calls. Common use cases:

Trigger a deployment rollback workflow from your CI/CD pipeline
Start an incident response workflow from a custom monitoring tool
Execute a maintenance workflow from a cron job or scheduler
Chain automation workflows across different platforms

Endpoint

POST /api/v1/automation/webhooks/{webhookKey}

Setting	Value
Method	`POST`
Content-Type	`application/json`
Authentication	Bearer token (`Authorization: Bearer <secret>`)
Rate Limit	60 requests per minute per webhook key
Idempotency	5-minute deduplication window

Authentication

Webhook requests require a Bearer token for authentication. The token (secret) is generated alongside the webhook key.

Enable Webhook Trigger

In the workflow designer, set the trigger type to Webhook in the Trigger node inspector.

Generate Webhook Key

Click Generate Webhook Key. This creates:

Webhook Key — Part of the URL (visible, not sensitive)
Webhook Secret — Bearer token for authentication (sensitive)

Copy the Secret

Copy the webhook secret immediately. It is displayed only once and cannot be retrieved later.

Include in Requests

Add the secret as a Bearer token in the Authorization header of your HTTP requests.

The webhook secret is shown only once when generated. If you lose it, you must regenerate the webhook key — which also changes the URL.

Request Format

Body (optional):

{
  "variables": {
    "key1": "value1",
    "key2": "value2",
    "nested": {
      "key": "value"
    }
  }
}

Field	Type	Required	Description
`variables`	object	No	Custom key-value pairs accessible in the workflow as `{{webhook.key}}`

The request body is optional. Sending an empty body or {} triggers the workflow without custom variables.

Response Format

Success (200 OK)

{
  "success": true,
  "data": {
    "executionId": "exec-abc123-def456",
    "status": "running",
    "startedAt": "2024-01-15T10:30:00.123Z"
  }
}

Duplicate Request (200 OK, cached)

If the same payload is sent within the 5-minute idempotency window:

{
  "success": true,
  "data": {
    "executionId": "exec-abc123-def456",
    "status": "running",
    "startedAt": "2024-01-15T10:30:00.123Z",
    "deduplicated": true
  }
}

Error Responses

Status	Code	Description
`401`	`unauthorized`	Missing or invalid Bearer token
`404`	`webhook_not_found`	Webhook key does not exist or workflow is inactive
`429`	`rate_limit_exceeded`	Too many requests (60/min limit)
`500`	`internal_error`	Server error during execution

Error format (RFC 7807):

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Invalid or missing webhook secret",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "instance": "/api/v1/automation/webhooks/wh_abc123"
}

Rate Limiting & Idempotency

Rate Limit

Each webhook key is limited to 60 requests per minute. Exceeding the limit returns HTTP 429 with a Retry-After header.

Idempotency

Duplicate detection prevents the same event from triggering multiple executions:

Mechanism	How It Works
Automatic	Payload hash is used as the idempotency key. Identical payloads within 5 minutes return the cached execution.
Explicit	Send `X-Idempotency-Key: your-unique-key` header. Requests with the same key within 5 minutes return the cached execution.

Use the X-Idempotency-Key header when your source system retries on failures. This prevents duplicate workflow runs even if the payload changes slightly between retries.

Code Examples

cURL
Python
Node.js
Go

curl -X POST \
  https://api.easyalert.io/api/v1/automation/webhooks/wh_abc123 \
  -H "Authorization: Bearer your_webhook_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "deployment": "v2.1.0",
      "environment": "production",
      "commit": "abc123def",
      "triggeredBy": "github-actions"
    }
  }'

import requests

response = requests.post(
    "https://api.easyalert.io/api/v1/automation/webhooks/wh_abc123",
    headers={
        "Authorization": "Bearer your_webhook_secret_here",
        "Content-Type": "application/json",
    },
    json={
        "variables": {
            "deployment": "v2.1.0",
            "environment": "production",
            "commit": "abc123def",
            "triggeredBy": "deploy-script",
        }
    },
)

if response.ok:
    data = response.json()
    print(f"Execution started: {data['data']['executionId']}")
else:
    print(f"Error {response.status_code}: {response.text}")

const response = await fetch(
  'https://api.easyalert.io/api/v1/automation/webhooks/wh_abc123',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_webhook_secret_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      variables: {
        deployment: 'v2.1.0',
        environment: 'production',
        commit: 'abc123def',
        triggeredBy: 'github-actions',
      },
    }),
  }
);

const data = await response.json();

if (response.ok) {
  console.log(`Execution started: ${data.data.executionId}`);
} else {
  console.error(`Error ${response.status}: ${data.detail}`);
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    payload := map[string]interface{}{
        "variables": map[string]string{
            "deployment":  "v2.1.0",
            "environment": "production",
            "commit":      "abc123def",
            "triggeredBy": "deploy-pipeline",
        },
    }

    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest(
        "POST",
        "https://api.easyalert.io/api/v1/automation/webhooks/wh_abc123",
        bytes.NewBuffer(body),
    )
    req.Header.Set("Authorization", "Bearer your_webhook_secret_here")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    if resp.StatusCode == 200 {
        data := result["data"].(map[string]interface{})
        fmt.Printf("Execution started: %s\n", data["executionId"])
    } else {
        fmt.Printf("Error %d: %s\n", resp.StatusCode, result["detail"])
    }
}

Using Variables in Workflows

Variables sent in the webhook payload are available in the workflow as {{webhook.<key>}}:

// Webhook payload
{
  "variables": {
    "deployment": "v2.1.0",
    "environment": "production",
    "services": ["payment-api", "auth-service"]
  }
}

Usage in workflow nodes:

Node	Template	Resolves To
Slack message	`Deploying {{webhook.deployment}} to {{webhook.environment}}`	`Deploying v2.1.0 to production`
Condition	`{{webhook.environment}}` equals `production`	Routes to production-specific flow
ForEach	Collection: `{{webhook.services}}`	Iterates over `["payment-api", "auth-service"]`

Nested variables are supported: {{webhook.config.timeout}} accesses {"variables": {"config": {"timeout": 30}}}.

Troubleshooting

401 Unauthorized

Cause: Missing or invalid Bearer token.Steps:

Verify the Authorization: Bearer <secret> header is present
Confirm the secret matches what was generated (it’s shown only once)
Check for extra whitespace or line breaks in the secret
If unsure, regenerate the webhook key and use the new secret

404 Webhook Not Found

Cause: The webhook key doesn’t exist, or the workflow is not active.Steps:

Verify the webhook key in the URL matches the one shown in the workflow settings
Confirm the workflow is published and activated
Check if the webhook key was regenerated (which changes the URL)

429 Rate Limited

Cause: More than 60 requests sent in one minute.Steps:

Check the Retry-After header for when to retry
Add backoff logic to your client
Batch events or reduce call frequency
Use X-Idempotency-Key to deduplicate retries safely

Variables not available in workflow

Cause: Variables not included in the variables field of the payload.Steps:

Verify your payload includes the "variables": {...} wrapper
Check that variable names match what the workflow expects (case-sensitive)
Verify the Content-Type header is application/json
Test with cURL to isolate whether the issue is client-side

Duplicate executions

Cause: Retries from your source system without idempotency.Steps:

Add X-Idempotency-Key header with a unique key per logical event
If using automatic dedup, note that different payloads create different executions even for the same logical event
The dedup window is 5 minutes — events older than 5 minutes are treated as new

​Overview

​Endpoint

​Authentication

​Request Format

​Response Format

​Success (200 OK)

​Duplicate Request (200 OK, cached)

​Error Responses

​Rate Limiting & Idempotency

​Rate Limit

​Idempotency

​Code Examples

​Using Variables in Workflows

​Troubleshooting

Overview

Endpoint

Authentication

Request Format

Response Format

Success (200 OK)

Duplicate Request (200 OK, cached)

Error Responses

Rate Limiting & Idempotency

Rate Limit

Idempotency

Code Examples

Using Variables in Workflows

Troubleshooting