Update Webhook

View as MarkdownEdit this pageReport an issueSet up docs MCP

PUT/api/v2/webhooks/{id}

Replaces an existing webhook. Readable optional fields (description, body) are a full replace: omitting them clears them. The write-only fields headers and queryParams are never returned on read, so omitting them preserves the stored values; send an explicit empty object ({}) to clear them. Exception: if the destination (url or service) changes, omitted headers/ queryParams are cleared rather than preserved so stored secrets are never forwarded to a new destination.

Authorizations

AuthorizationBearer API Keyheaderrequired
`Authorization: Bearer <token>`

Path parameters

idstringrequired
Webhook ID

Request bodyJSON

namestringrequired
Webhook name. Must be unique per service within the team.

maxLength: 1024
Example: "Production Alerts"
serviceslackorincidentioorgenericrequired
Webhook service type.

Example: "slack"
urlstringrequired
Webhook destination URL.

format: uri, maxLength: 2048
Example: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
descriptionoptionalstring
Webhook description, shown in the UI.

maxLength: 2048
Example: "Sends critical alerts to the #incidents channel"
bodyoptionalstring
Optional request body template. Only for generic/incidentio; rejected for slack.

maxLength: 16384
Example: "{\"alert\": \"{{title}}\", \"severity\": \"{{level}}\"}"
headersoptionalmap ofstring
Write-only. Custom HTTP headers sent with the webhook request. Never returned on read. Only for generic/incidentio; rejected for slack. Each value is capped at 4096 characters.

Example: {"Authorization":"Bearer secret-token"}
queryParamsoptionalmap ofstring
Write-only. Query parameters appended to the webhook URL. Never returned on read. Only for generic/incidentio; rejected for slack. Each value is capped at 4096 characters.

Response

JSON

200

Successfully updated webhook

JSON

dataoptionalSlackWebhookorIncidentIOWebhookorGenericWebhook
The webhook object.
3 variants
One of the following:
SlackWebhookslack
View SlackWebhook schema →
7 properties
idstringrequired
Webhook ID

Example: "507f1f77bcf86cd799439011"
namestringrequired
Webhook name

Example: "Production Alerts"
serviceslackrequired
Webhook service type

Example: "slack"
updatedAtstringrequired
Last update timestamp

format: date-time
Example: "2025-06-15T10:30:00.000Z"
createdAtstringrequired
Creation timestamp

format: date-time
Example: "2025-01-01T00:00:00.000Z"
urloptionalstring
Slack incoming webhook URL

Example: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
descriptionoptionalstring
Webhook description, shown in the UI

Example: "Sends critical alerts to the #incidents channel"
IncidentIOWebhookincidentio
View IncidentIOWebhook schema →
7 properties
idstringrequired
Webhook ID

Example: "507f1f77bcf86cd799439012"
namestringrequired
Webhook name

Example: "Incident Response"
serviceincidentiorequired
Webhook service type

Example: "incidentio"
updatedAtstringrequired
Last update timestamp

format: date-time
Example: "2025-06-15T10:30:00.000Z"
createdAtstringrequired
Creation timestamp

format: date-time
Example: "2025-01-01T00:00:00.000Z"
urloptionalstring
incident.io alert event HTTP source URL

Example: "https://api.incident.io/v2/alert_events/http/abc123"
descriptionoptionalstring
Webhook description, shown in the UI

Example: "Routes alerts to incident.io for on-call escalation"
GenericWebhookgeneric
View GenericWebhook schema →
8 properties
idstringrequired
Webhook ID

Example: "507f1f77bcf86cd799439013"
namestringrequired
Webhook name

Example: "PagerDuty Integration"
servicegenericrequired
Webhook service type

Example: "generic"
updatedAtstringrequired
Last update timestamp

format: date-time
Example: "2025-06-15T10:30:00.000Z"
createdAtstringrequired
Creation timestamp

format: date-time
Example: "2025-01-01T00:00:00.000Z"
urloptionalstring
Webhook destination URL

Example: "https://example.com/webhooks/alerts"
descriptionoptionalstring
Webhook description, shown in the UI

Example: "Forwards alert payloads to an external monitoring service"
bodyoptionalstring
Optional request body template

Example: "{\"alert\": \"{{title}}\", \"severity\": \"{{level}}\"}"

Update Webhook

curl --request PUT \
  --url /api/v2/webhooks/string \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Production Alerts",
  "service": "slack",
  "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
  "description": "Sends critical alerts to the #incidents channel",
  "body": "{\"alert\": \"{{title}}\", \"severity\": \"{{level}}\"}",
  "headers": {
    "Authorization": "Bearer secret-token"
  },
  "queryParams": {
    "property1": "string",
    "property2": "string"
  }
}
'

const url = '/api/v2/webhooks/string';
const options = {
  method: 'PUT',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    name: 'Production Alerts',
    service: 'slack',
    url: 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX',
    description: 'Sends critical alerts to the #incidents channel',
    body: JSON.stringify('{"alert": "{{title}}", "severity": "{{level}}"}'),
    headers: {Authorization: 'Bearer secret-token'},
    queryParams: {property1: 'string', property2: 'string'}
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "/api/v2/webhooks/string"

payload = {
    "name": "Production Alerts",
    "service": "slack",
    "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "description": "Sends critical alerts to the #incidents channel",
    "body": "{\"alert\": \"{{title}}\", \"severity\": \"{{level}}\"}",
    "headers": { "Authorization": "Bearer secret-token" },
    "queryParams": {
        "property1": "string",
        "property2": "string"
    }
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

Response example

{
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Production Alerts",
    "service": "slack",
    "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "description": "Sends critical alerts to the #incidents channel",
    "updatedAt": "2025-06-15T10:30:00.000Z",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

{
  "message": "NOT_FOUND: Alert not found"
}

{
  "message": "NOT_FOUND: Alert not found"
}

{
  "message": "NOT_FOUND: Alert not found"
}

{
  "message": "NOT_FOUND: Alert not found"
}

{
  "message": "NOT_FOUND: Alert not found"
}