Webhooks - Chalk

Chalk can send push notifications to configured external endpoints through webhooks.

Webhooks are in beta. Contact our support team to enable webhooks in your environments.

Add a webhook

Go to Alerting > Webhooks and select New Webhook. The page lists each webhook with its URL, subscriptions, and creation time, and has actions to test, edit, and delete a webhook.

The form has these fields:

Name: A label for the webhook.
URL: The endpoint that receives the events.
Subscriptions: The events that trigger the webhook. See Available subscriptions for the catalog.
Secret (optional): A shared secret that Chalk uses to sign each request. See Request format.
Headers (optional): A JSON object of additional headers to send with each request, such as an Authorization header.

Request format

Chalk sends each event to the webhook URL as a POST request with a JSON body. The request includes these headers:

Content-Type is application/json.
User-Agent is Chalk-Webhook/1.0.
Each custom header that you configured is included. Header values must be strings.
X-Chalk-Signature is included when the webhook has a secret. Its value is the hex-encoded HMAC-SHA256 of the request body, computed with the secret.

Chalk waits up to 10 seconds for a response.

Webhook schema

Every webhook sends a JSON body that contains the following fields:

subscription: The name of the action that triggered this webhook. See below for options.
payload: A map of strings whose content varies based on the specific subscription triggered. Individual action fields are documented below.
environment_id: The environment originating the webhook.
webhook_id: A unique ID for the configured webhook.
idempotency_key: A unique key for the webhook event.
event_timestamp: The original time the event was published, in RFC 3339 format.

{
  "environment_id": "chalk-env-id",
  "webhook_id": "cea28e03-e4e9-4e42-a3cb-38b6790d8700",
  "subscription": "incident.closed",
  "payload": {
    "environment_id": "chalk-env-id",
    "incident_id": "cmk7lk72s000y012slnh1u863",
    "incident_url": "https://staging.chalk.dev/projects/tmnmau5shs3qe/environments/tmnmc9beyujew/incidents/cmk7lk72s000y012slnh1u863",
    "metric_id": "cmgk1rdpp0000knttvtku94xh",
    "metric_name": "Failed Query Count Too High",
    "project_id": "chalk-proj-id",
    "severity": "Resolved",
    "summary": "Chalk Metric Alert Resolved: Failed Query Count Too High"
  },
  "event_timestamp": "2026-01-10T02:06:05.577233847Z",
  "idempotency_key": "cmk7nym6i000h01znf7w4w6fv"
}

Available subscriptions

Chalk supports webhook subscriptions for incidents, deployments, branch deployments, and offline queries.

Incidents

Incident Opens (incident.opened): When a metric chart goes over its alert threshold and opens a Chalk incident. The payload contains:

incident_id: The Chalk internal unique ID for the incident.
incident_url: A Chalk dashboard URL for the incident.
metric_id: The Chalk internal unique ID for the chart that triggered the incident.
metric_name: The name of the alert on the chart that triggered the incident.
severity: The severity of the configured alert. One of Info, Warning, Error, and Critical.
summary: A human-readable title message about the incident.
environment_id: The ID of the environment containing the incident.
project_id: The ID of the project containing the environment.

Incident Closes (incident.closed): When a metric chart returns below its alert threshold and closes a Chalk incident. Includes the same payload fields, except that severity is always Resolved.

Deployments

All deployment payloads have these fields, in addition to any subscription-specific fields:

deployment_id: The ID of the deployment.
deployment_url: A Chalk dashboard URL for the deployment.
environment_id: The environment ID for the deployment.
project_id: The ID of the project containing the environment.

Chalk does not send these events for rebuilds, patches, or indexing.

The following subscriptions are available:

Deployment Starts (deploy.started): When a deployment starts. Contains no extra payload fields.

Deployment Fails (deploy.failed): When a deployment fails to build or start. Contains an error field with more detail. A deployment that times out instead contains status and a reason of deployment_timeout.

Deployment Succeeds (deploy.succeeded): When a deployment successfully spins up. Contains no extra payload fields.

Branch deployments

Branch deployment payloads have the deployment fields above and a branch_name field with the name of the branch. They are separate from deployment subscriptions, so a webhook that subscribes to deploy.started does not receive branch deployment events.

The following subscriptions are available:

Branch Deployment Starts (branch_deployment.started): When a branch deployment starts.

Branch Deployment Fails (branch_deployment.failed): When a branch deployment fails. Contains a status field.

Branch Deployment Succeeds (branch_deployment.succeeded): When a branch deployment succeeds. Contains a status field.

Offline queries

All offline query webhooks share these payload fields:

environment_id: The environment ID for the offline query.
deployment_id: The deployment ID used for the offline query.
operation_id: The unique ID for the offline query run.
status: The offline query status enum value. Terminal webhook events send one of 1 (COMPLETED), 2 (FAILED), or 3 (CANCELED).
query_name: The query name, if one was provided when the offline query was created.
query_name_version: The version of the query name, if present.
dataset_name: The dataset produced by the offline query, if present.
dataset_id: The dataset ID, if present.
correlation_id: The correlation ID for the offline query, if present.
branch_name: The branch name for the offline query, if present.
created_at: The time the offline query was created, in RFC 3339 format.
completed_at: The time the offline query entered its terminal state, in RFC 3339 format.
total_shards: The total number of shards in the offline query.
total_computers: The total number of computers assigned to the offline query, if known.

Shard-level offline query webhooks also include:

shard_id: The shard index that entered a terminal state.
computer_id: The computer ID that processed the shard, if known.
num_rows: The number of rows written by the shard, if known.
physical_size_bytes: The physical output size for the shard, in bytes, if known.
shard_completed_at: The time the shard entered its terminal state, in RFC 3339 format.

The following subscriptions are available:

Offline Query Shard Completes (offline_query.shard_completed): When an individual offline query shard completes successfully. Includes the shared fields and the shard-specific fields.

Offline Query Completes (offline_query.query_completed): When the full offline query completes successfully. Includes the shared fields and no shard-specific fields.

Offline Query Shard Cancels (offline_query.shard_canceled): When an individual offline query shard is canceled. Includes the shared fields and the shard-specific fields.

Offline Query Cancels (offline_query.query_canceled): When the full offline query is canceled. Includes the shared fields and no shard-specific fields.

Offline Query Shard Fails (offline_query.shard_failed): When an individual offline query shard fails. Includes the shared fields and the shard-specific fields.

Offline Query Fails (offline_query.query_failed): When the full offline query fails. Includes the shared fields and no shard-specific fields.

Test webhooks

To test a webhook, select its test action on the Webhooks page. Chalk sends a test event with the webhook.test subscription.

FireHydrant support

Chalk webhooks can be configured as a custom event source for FireHydrant, using the example webhook body as a testing source. Some subscriptions will have a summary in their payload, and some subscriptions may have non-string values in their payload. To mitigate this, we suggest the following transposition script:

/*
 * Transpose a payload from a webhook into a signal.
 *
 * @returns {{summary: string, body: string, level: number, links: {href: string, text: string}[], images: {src: string, alt: string}[], tags: string[], idempotency_key: string, status: number}} Signal object.
 */
function transpose(input) {
  return {
    summary: input.data.payload?.summary || `Chalk Webhook: ${input.data.subscription}`,
    annotations: Object.fromEntries(
      Array.from(Object.entries(input.data.payload)).map(([key, val]) => [key, `${val}`])
    )
  }
}

Help

If you need help with your integration, contact us at support@chalk.ai.

​Add a webhook

​Request format

​Webhook schema

​Available subscriptions

​Incidents

​Deployments

​Branch deployments

​Offline queries

​Test webhooks

​FireHydrant support

​Help

On this page

Add a webhook

Request format

Webhook schema

Available subscriptions

Incidents

Deployments

Branch deployments

Offline queries

Test webhooks

FireHydrant support

Help