Update a webhook

Change where events go, which events you get, or pause delivery.

PATCH /v1/webhooks/{id}

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The webhook id.

Body parameters

Every field is optional; send only what you're changing.

Parameter	Type	Description
endpoint	string	A new HTTPS URL. Same public-address rule as on create.
events	string[]	Replaces the subscribed set — send the full list you want, not a delta. Each from the event catalog.
name	string | null	A label for your own use.
status	string	enabled or disabled.

events replaces, it does not merge

Sending events overwrites the whole set. To add one event to a webhook already on three, send all four — sending just the new one leaves you subscribed to only that one.

Example

curl

curl -X PATCH "https://api.sendgrail.com/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "endpoint": "https://example.com/new-handler",
    "events": ["email.sent", "email.delivered"],
    "status": "enabled"
  }'

Node.js

await fetch(`https://api.sendgrail.com/v1/webhooks/${id}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    endpoint: 'https://example.com/new-handler',
    events: ['email.sent', 'email.delivered'],
    status: 'enabled',
  }),
});

Response

The updated object, without the signing secret — updating does not change it:

{
  "object": "webhook",
  "id": "4dd369bc-aa82-4ff3-97de-514ae3000ee0",
  "name": "Production handler",
  "endpoint": "https://example.com/new-handler",
  "events": ["email.sent", "email.delivered"],
  "status": "enabled",
  "created_at": "2026-08-22T15:28:00+00:00"
}

Pausing instead of deleting

Set status to disabled to stop delivery while keeping the webhook, its id and its signing secret. This is what you want when your handler is down for a deploy or a bug fix: no events are sent while disabled, and flipping back to enabled resumes without you having to re-register anything or update your signature verification.

Events that occur while a webhook is disabled are not queued — they are not delivered when you re-enable it. Disable pauses the future, it does not bank the past.