Skip to content

Update a webhook ​

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

http
PATCH /v1/webhooks/{id}

Requires a Full access API key.

Path parameters ​

ParameterTypeRequiredDescription
idstringYesThe webhook id.

Body parameters ​

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

ParameterTypeDescription
endpointstringA new HTTPS URL. Same public-address rule as on create.
eventsstring[]Replaces the subscribed set — send the full list you want, not a delta. Each from the event catalog.
namestring | nullA label for your own use.
statusstringenabled 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 ​

bash
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"
  }'
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:

json
{
  "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.

Transactional email on your own domain.