Webhooks

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

Webhooks are a beta feature for Chalk - contact our support team to get webhooks enabled in your environments.

​

Add a Webhook

Webhook configuration is under the settings sidebar, under Environment. Users can configure:

• The webhook endpoint
• Subscriptions - see below for the catalog of subscriptions available
• Any additional headers necessary to communicate with the webhook

​

Webhook Schema

All webhooks will pass a JSON body containing 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 and deployments.

​

Incidents

Incident Opens (incident.opened): When a metric chart goes over their 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 their alert threshold and closes a Chalk incident. Includes the same payload fields, except that severity is always Resolved.

​

Deployments

All deployment and apply payloads have shared fields, in addition to action-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.

The following subscriptions are available:

Apply Starts (apply.started): When a chalk apply action successfully starts. Contains no extra payload fields.

Apply Validation Error (apply.validation_failed): When a chart apply action fails to start due to source code or environment configuration errors. Contains an error field with more detail.

Deployment Fails (deployment.failed): When a deployment fails to start up successfully. Contains a reason for the failed deployment.

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

​

Test Webhooks

Webhooks can be tested from the web dashboard and will send a test event with a 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, please contact us at support@chalk.ai.