> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbound Webhooks

> Create a webhook URL that runs an Automation or sends alerts to Resolve, then authenticate, test, and debug it.

A webhook is a URL that CloudThinker issues for you. Another system sends an HTTPS POST with a JSON body to that URL, and CloudThinker either runs an [Automation](https://docs.cloudthinker.io/guide/automation/automations.md) or turns the request into an alert in [Resolve](https://docs.cloudthinker.io/guide/incident/overview.md).

> [!NOTE]
>
> Webhooks here are inbound only. CloudThinker doesn't POST events out to your endpoints. To send results outward, use [notifications](https://docs.cloudthinker.io/guide/notifications.md), [Slack](https://docs.cloudthinker.io/guide/slack-integration.md) or [Microsoft Teams](https://docs.cloudthinker.io/guide/teams-integration.md).

## Pick the kind of webhook

There are two kinds. They're created in different places and do different things with a request.

| Kind | Create it in | What one request does | Use it when |
| - | - | - | - |
| **Automation webhook trigger** | An Automation's triggers | Starts a run of that Automation. The request body reaches the agent as data. | You want an agent to do a job when something happens, like a deploy finishing or a ticket being filed. |
| **Resolve webhook signal** | **Resolve → Triggers & Outcomes** | Sends an alert through [Pulse](https://docs.cloudthinker.io/guide/pulse/overview.md), which can open an incident and start a root cause analysis (RCA). | You want alerts from a monitoring tool like Datadog, Grafana, or PagerDuty investigated. |

## Prerequisites

* A system that can send HTTPS POST requests with a JSON body and a custom header.
* The **Admin** workspace role, for both kinds. Developers and Viewers can see webhooks but can't create them. See [Workspace users](https://docs.cloudthinker.io/guide/workspace-users.md).
* For an Automation trigger: an existing Automation.
* For a Resolve webhook: admin access to the monitoring tool, so you can add the webhook to it.

## Create an Automation webhook trigger

**1. Open the Automation**

Open the Automation from the **Automations** page and find the **Triggers** section.

**2. Add a Webhook trigger**

Choose **Webhook**. If the Automation already has a trigger, click **Add another trigger** first, then **Webhook**. CloudThinker creates the trigger at once and opens the **Webhook trigger added** dialog with the URL, a secret, and a ready-to-paste **Test command**.

**3. Copy the secret**

Copy the URL and the secret before you select **Done**. The secret is shown only once.

Every webhook URL, for both kinds, has this shape:

```text theme={null}
https://<CloudThinker API host>/api/v1/webhooks/webhook/<token>/trigger
```

**Success state:** the trigger card shows the webhook, and each call you send appears in its delivery list.

> [!TIP]
>
> Lost the secret? Use **Rotate webhook secret** on the trigger card. The URL stays the same, but every caller needs the new secret.

The Automation's own on/off switch must be on, or the trigger won't start a run.

## Create a Resolve webhook

**1. Open the platform**

Go to **Resolve → Triggers & Outcomes** and select your tool, for example Datadog, Grafana, or PagerDuty.

**2. Add a signal**

Under **Signals to Resolve**, click **Add signal**. The **Create Webhook** dialog opens with three steps.

**3. Basic Info**

Keep or change **Webhook Name** and add an optional **Description**. Click **Next**.

**4. Configure**

Check **Field Mapping** and **Severity Mapping**. Both come pre-filled for the tool you picked. Click **Next**.

**5. Advanced**

Pick an **Auth Method** and set **Auto-investigate**. The PagerDuty preset already picks **HMAC Signature** with **HMAC Signature Header** set to `X-PagerDuty-Signature`; keep that header, or PagerDuty's signatures fail the check. With Auto-investigate on, you can also turn on **Only from a minimum severity** (off by default; it starts at High when you turn it on), so lower alerts don't start an RCA. Click **Create**.

**Success state:** a dialog shows the **Webhook URL**, the secret under **Authentication Setup**, and **Integration Examples**. Copy the URL and secret now and paste them into your monitoring tool.

Field mapping, severity mapping, and when RCA starts are covered in [Webhook signals](https://docs.cloudthinker.io/guide/incident/webhook-integrations/overview.md). If your tool has no preset, use [Custom source](https://docs.cloudthinker.io/guide/incident/webhook-integrations/custom-source.md).

## Authenticate requests

An Automation webhook trigger always uses a Bearer token: the caller sends `Authorization: Bearer <secret>`. A Resolve webhook lets you pick the **Auth Method**.

| Auth Method | The sender includes | Use when |
| - | - | - |
| **Bearer Token** | `Authorization: Bearer <secret>` | The tool lets you add a custom header. The default for most tools. |
| **HMAC Signature** | A signature of the body in the **HMAC Signature Header** (default `X-Webhook-Signature`) | The tool signs its own webhooks, like PagerDuty. The PagerDuty preset sets the header to `X-PagerDuty-Signature` for you. |
| **API Key** | The key in the **API Key Header** (default `X-Api-Key`), after an optional **Key Prefix** | The tool only supports API key headers, like CloudWatch through EventBridge. |
| **No Authentication** | Nothing | Only for a quick test. Anyone with the URL could send alerts. |

HMAC Signature and API Key apply to Resolve webhooks only. You set both header names in the **Advanced** step.

**Resolve webhook, HMAC Signature.** If you sign requests yourself, sign the raw body with HMAC-SHA256 and send the digest as `sha256=<hex>` in the header you set (the default here):

```bash theme={null}
BODY='{"title": "High CPU on web-server-01", "alert_type": "critical"}'
SIGNATURE="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex | awk '{print $2}')"

curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIGNATURE" \
  -d "$BODY"
```

**Resolve webhook, API Key.** Send the key in the header you set (the default here):

```bash theme={null}
curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $WEBHOOK_SECRET" \
  -d '{"title": "High CPU on web-server-01"}'
```

## What to send

Both kinds share one request format. Send a JSON object of up to 1 MB to the webhook URL.

### Request

| Part | Automation trigger | Resolve webhook |
| - | - | - |
| Method | `POST` | `POST` |
| URL | `https://<CloudThinker API host>/api/v1/webhooks/webhook/<token>/trigger` | Same shape, with the Resolve webhook's token |
| `Content-Type` | `application/json` | `application/json` |
| Auth header | `Authorization: Bearer <secret>` | Depends on the **Auth Method** |
| Body | A JSON object, up to 1 MB | A JSON object, up to 1 MB |

Header details for a Resolve webhook, beyond [Authenticate requests](#authenticate-requests):

* **HMAC Signature:** the value is `sha256=` plus the lowercase hex HMAC-SHA256 of the raw body, keyed with the secret. When the header is set to `X-PagerDuty-Signature`, CloudThinker reads PagerDuty's own format instead: one or more comma-separated `v1=<hex>` values, and any one match passes.
* **API Key:** with a **Key Prefix** set, the header value must start with that prefix. CloudThinker drops the prefix and any surrounding spaces, then compares the rest with the secret.

A body that isn't a JSON object (an array, a string, or text that isn't JSON) is refused with `422`. CloudThinker doesn't read an idempotency key, so a sender's retry counts as a new call.

### Body: Automation trigger

Any JSON object works. The whole body reaches the agent after the Automation's instructions, so it needs no template setup. The agent sees up to 50,000 characters of it; anything past that is cut. The body is treated as data, never as instructions, so a caller can't change what the agent is told to do.

```json theme={null}
{
  "message": "Deploy of checkout-api finished",
  "environment": "production",
  "commit": "a1b2c3d"
}
```

### Body: Resolve webhook

Send your tool's own alert payload as it is. The webhook's **Field Mapping** picks fields out of it by JSON path, like `event.data.title`. A leading `$` in a path is dropped, and a path can have up to 8 segments.

| Mapped field | Required |
| - | - |
| Title | Yes |
| Description, Severity, Service, Resource ID, Resource name, Timestamp | No |

The value at the severity path is translated by the webhook's **Severity Mapping**. A minimal custom payload:

```json theme={null}
{
  "title": "High CPU on web-server-01",
  "alert_type": "critical",
  "service": "checkout-api"
}
```

### Amazon SNS

When a request carries the `x-amz-sns-message-type` header, CloudThinker treats it as Amazon SNS. It checks the SNS signature, confirms a `SubscriptionConfirmation` on its own, and unwraps a `Notification` so the inner message is the body. The webhook's auth still applies to every SNS request.

### Response

A call that passes auth and validation gets HTTP `200` with this body:

```json theme={null}
{"success": true, "request_id": "req_..."}
```

`200` means CloudThinker queued the call. The run or the alert happens a moment later, so check the result (see [Test with curl](#test-with-curl)). Keep the `request_id` if you contact support about a call.

Other outcomes are below. A call can pass auth and still get `400`, `413`, `422` or `429`.

| HTTP | Body `detail` | Cause |
| - | - | - |
| `400` | `Webhook is not active` | The webhook is turned off |
| `401` | `Missing Authorization header`, or `Missing <header> header` | The auth header is missing |
| `401` | `Invalid webhook token` | The token in the URL is wrong, or the webhook was deleted. A wrong token and a deleted one answer the same way on purpose, so nobody can discover which webhooks exist |
| `403` | `Invalid bearer token`, `Invalid webhook signature`, `Invalid API key` and similar | The header is there, but the secret or signature doesn't match |
| `413` | `Request body exceeds 1MB limit` | The body is over 1 MB |
| `422` | A validation error | The body isn't a JSON object |
| `429` | A rate limit message | Too many calls or too many failed authentications. See [Rate limits and busy runs](#rate-limits-and-busy-runs). A `429` that says `Webhook ingress is busy` carries a `Retry-After` header; retry after that many seconds. |

Errors use the body `{"detail": "..."}`.

## Test with curl

Use the **Test command** from the Automation dialog, or the **Integration Examples** from the Resolve dialog. A minimal Bearer request looks like this:

```bash theme={null}
curl -X POST "$WEBHOOK_URL" \
  -H "Authorization: Bearer $WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"message": "hello"}'
```

**Expected result:** CloudThinker answers `200` with `{"success": true, "request_id": "req_..."}`. That only proves delivery, so check the result too.

| Kind | Where to check | What you should see |
| - | - | - |
| Automation trigger | The trigger card's delivery list, and the **Runs** tab on the **Automations** page | A delivery marked **Accepted** then **Processed**, and a run labeled **Webhook** |
| Resolve webhook | **Resolve → Pulse**, then **Resolve → Investigation** | A signal with the title you mapped. If Pulse groups it into a cluster that holds an actionable signal, an incident. See [How Pulse works](https://docs.cloudthinker.io/guide/pulse/overview.md#how-it-works). |

For a Resolve webhook, send one normal alert and one critical alert, so you know both severity mappings work.

An Automation trigger's delivery list marks each call with a status:

| Status | Meaning | What to do |
| - | - | - |
| **Accepted** | CloudThinker received the call and queued it. | Wait a moment. |
| **Processed** | The call started a run, or was held for one. A held call that a newer call replaces, or that is still waiting after 30 minutes, stays **Processed** but never runs. | Check the **Runs** tab. If no run is there, read the note on the trigger card. |
| **Rate limited** | The call was over the webhook's hourly limit and started nothing. | Slow the sender or batch events. |
| **Failed** | The call couldn't be processed. The error text says why. | Fix the cause and send again. |

## Rate limits and busy runs

Each webhook has an hourly limit: 60 calls per hour for an Automation trigger, and 1,000 per hour by default for a Resolve webhook. A call over the limit still gets `200` but starts nothing, and an Automation trigger lists it as **Rate limited**. A sender that goes far past the limit (10 times over) gets `429`. After 10 failed authentications in 15 minutes, the webhook also answers `429` for a while. If your sender bursts, batch events into one request or slow it down.

An Automation runs one run at a time. A call that arrives mid-run is held, and CloudThinker retries it every minute for up to 30 minutes. If a run is already going, expect the held call's run to show as **Pending** on the **Runs** tab.

> [!WARNING]
>
> Only one call is held per trigger. A newer call replaces the held one, so earlier held calls never run. If every event matters, batch them into one request.

> [!WARNING]
>
> After 10 failed runs in a row, CloudThinker turns the Automation off and sends the **Automation turned off** notification. Webhook calls then stop starting runs until you fix the cause and turn it back on.

## Troubleshooting

> [accordion] 401 or 403 on every request
>
> `401` means the auth header is missing, or the token in the URL is wrong; `403` means the header is there but the secret or signature doesn't match. An Automation trigger only accepts `Authorization: Bearer <secret>`. For a Resolve webhook, compare the header name and secret in your tool with **Authentication Setup**. After 10 failures in 15 minutes the webhook answers `429` for a while, so fix the header before you retry. If the secret is lost, use **Rotate webhook secret** on the trigger card (Automation), or open **Resolve → Triggers & Outcomes**, select the tool, open the webhook's menu under **Signals to Resolve**, and choose **Regenerate credentials** (Resolve). Then update every sender with the new values.

> [accordion] HMAC signature mismatch
>
> Sign the exact raw body bytes you send. Reformatting or re-serializing the JSON after signing changes the bytes and breaks the signature.

> [accordion] 413 or a rejected large payload
>
> The body is over 1 MB. Send a short summary plus a link or ID the agent can look up, instead of the full document.

> [accordion] 200 response but no Automation run
>
> Check the delivery on the trigger card. **Rate limited** means the sender is too fast. **Failed** shows the error text. Also check that the Automation's switch is on, and look for a **Pending** run waiting behind a busy one. A **Processed** call with no run was held while a run was going, then replaced by a newer call or dropped after 30 minutes; the trigger card's note says why the last call started no run. See [Rate limits and busy runs](#rate-limits-and-busy-runs).

> [accordion] 200 response but nothing in Resolve
>
> Pulse may have suppressed the alert as noise, or the time window hides it. Widen the window on **Resolve → Pulse**. If the signal is there with an empty title or wrong severity, fix the path in **Field Mapping** or add the missing value to **Severity Mapping**.

> [accordion] An incident opened but no RCA started
>
> **Auto-investigate** is off, the alert is below **Only from a minimum severity** (set in the webhook's **Advanced** step), or **On duty** on **Resolve → Investigation** shows **Paused**. Check all three, or start the investigation by hand.

## Related

> [card] [Automations](https://docs.cloudthinker.io/guide/automation/automations.md)
>
> Write the instructions a webhook call runs, and review every run.

> [card] [Webhook Signals](https://docs.cloudthinker.io/guide/incident/webhook-integrations/overview.md)
>
> Map alert fields and choose when Resolve investigates on its own.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.