Webhooks

Webhooks let external systems push events into CloudThinker. Each webhook gives you a unique URL; POST to it and CloudThinker starts an agent conversation or opens a DRE incident.

Webhooks are inbound only. CloudThinker does not POST events out to your endpoints. To send results outward, use notifications, Slack, or Microsoft Teams.

How it works

You create a webhook and choose what it does: start a Conversation or open a DRE incident.
CloudThinker issues a unique URL containing the webhook token, plus a signing secret shown once.
Your system POSTs a JSON body to that URL.
CloudThinker authenticates the request, checks the rate limit, records the event, and returns 202 Accepted in under 100 ms.
A worker dispatches the payload and writes the final status.

Create a webhook

Open Webhooks

Navigate to Webhooks in the sidebar, or open Chat Settings (the gear icon beside the + button in the chat prompt box) and select Webhooks under Integrations.

Click Create Webhook

The wizard has four steps: Basic Info, Type, Configure, and Advanced.

Fill in the fields

Name — a descriptive identifier
Description — optional
Type — Conversation or DRE
Rate limit — requests per hour, default 100. Set 0 or below for unlimited
Prompt structure — optional template that must contain {{message}}
Auth — bearer token, HMAC, API key, or none

Copy the URL and secret

Save the webhook, then copy its URL and signing secret.Success state: the webhook appears in the list as active.

The signing secret is shown only once, when you create the webhook. Store it before you close the dialog.

Action types

Type	What a request does
Conversation	Starts an agent conversation from the payload. `message` is required
DRE	Opens an incident, and optionally runs automatic RCA. `message` is optional

For a DRE webhook, automatic RCA is on by default with a minimum severity of Medium. See webhook integrations.

Request body

{
  "message": "Hello from webhook!",
  "metadata": {
    "source": "external-system",
    "priority": "normal"
  }
}

Field	Required	Description
`message`	For Conversation webhooks	The prompt the agent receives
`metadata`	No	Custom fields carried into the incident payload

Unknown top-level fields are silently dropped. Put every custom field inside metadata.

The response returns success, request_id, and — depending on the action type — conversation_id, incident_id, rca_run_id, and signal_id.

Authentication

Choose one auth mode per webhook. CloudThinker verifies each incoming request before it accepts the payload.

Mode	How the sender authenticates
Bearer	`Authorization: Bearer <token>`
HMAC	A signature header, `X-Webhook-Signature` by default, computed with the webhook’s signing secret
API key	A key header, `X-Api-Key` by default
None	No authentication. Rely on the unguessable token in the URL

The header name is configurable for HMAC and API key. Sign the raw request body with HMAC-SHA256 and send sha256=<hex digest>:

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"

Limits

Limit	Value
Request body	1 MB
Rate limit	100 requests per hour by default; 0 or below means unlimited
Raw body retention	90 days

A request over the rate limit is recorded with status rate_limited.

Review triggers

Navigate to Webhooks > Triggers to see every webhook trigger in the workspace.

Column	What it shows
Type	Chat, Incident, System, or Auth Failed
Request ID	The identifier returned to the sender
Status	The HTTP status code
Duration	Processing time in milliseconds
Error	The failure reason, when one exists
Created	When the request arrived
Actions	A View Incident link for incident triggers

Each event carries one of four lifecycle statuses: accepted, processed, failed, or rate_limited.

Triggers never expose stored request headers, bodies, or client details. That data is retained internally for 90 days and redacted from the interface.

Pause a webhook

Set the webhook to paused to stop it accepting requests. A webhook is active, paused, or disabled. While paused, the endpoint rejects incoming requests rather than queueing them.

Troubleshooting

401 or 403 on every request

The auth mode does not match what you send. Check the header name and confirm you are signing with the webhook’s own secret. A failed attempt appears in Triggers as Auth Failed.

Signature mismatch

Sign the exact raw body bytes, before any reformatting, and send the digest as sha256=<hex>. Re-serializing JSON changes the bytes and breaks the signature.

Custom fields never reach the agent

Unknown top-level keys are dropped. Move them inside metadata.

429 responses

The webhook is over its hourly rate limit. Raise the limit, or set it to 0 for unlimited.

413 or a rejected large payload

The body is over the 1 MB cap. Send a reference instead of the full document.

DRE Webhook Integrations

Route alerts from monitoring platforms into incidents

Notifications

Deliver CloudThinker results to email, Slack, and Teams

APIs & Tooling

Deployment

How it works

Create a webhook

Action types

Request body

Authentication

Limits

Review triggers

Pause a webhook

Troubleshooting

DRE Webhook Integrations

Notifications

​How it works

​Create a webhook

​Action types

​Request body

​Authentication

​Limits

​Review triggers

​Pause a webhook

​Troubleshooting

​Related

DRE Webhook Integrations

Notifications

How it works

Create a webhook

Action types

Request body

Authentication

Limits

Review triggers

Pause a webhook

Troubleshooting

Related