Skip to contentSkip to navigationSkip to topbar
On this page

Update an Event Webhook



API Overview

api-overview page anchor

The SendGrid Event Webhook sends email event data as SendGrid processes it. This means you can receive data in nearly real-time, making it ideal to integrate with logging or monitoring systems.

Because the Event Webhook delivers data to your systems, it is also well-suited to backing up and storing event data within your infrastructure to meet your own data access and retention needs.


You can think about the types of events provided by the Event Webhook in two categories: deliverability events and engagement events.

  • Deliverability events such as "delivered," "bounced," and "processed" help you understand if your email is being delivered to your customers.
  • Engagement events such as "open," and "click" help you understand if customers are reading and interacting with your emails after they arrive.

Both types of events are important and should be monitored to understand the overall health of your email program. The Webhooks API allows you to configure your Event Webhook configurations.


Currently, data staged to be be posted through the webhooks is stored in the US.


PATCH/v3/user/webhooks/event/settings/{id}

Base url: https://api.sendgrid.com (for global users and subusers)

Base url: https://api.eu.sendgrid.com (for EU regional subusers)

This endpoint allows you to update a single Event Webhook by ID.

If you do not pass a webhook ID to this endpoint, it will update and return your oldest webhook by created_date. This means the default webhook updated by this endpoint when no ID is provided will be the first one you created. This functionality allows customers who do not have multiple webhooks to use this endpoint to update their only webhook, even if they do not supply an ID. If you have multiple webhooks, you can retrieve their IDs using the Get All Event Webhooks endpoint.

Enable or disable the webhook

enable-or-disable-the-webhook page anchor

You can set the enabled property to true to enable the webhook or false to disable it. Disabling a webhook will not delete it from your account, but it will prevent the webhook from sending events to your designated URL.

A webhook's URL is the endpoint where you want the webhook to send POST requests containing event data. No more than one webhook may be configured to send to the same URL. SendGrid will return an error if you attempt to set a URL for a webhook that is already in use by the user on another webhook.

If an event type is marked as true, the event webhook will send information about that event type. See the Event Webhook Reference for details about each event type.

You may assign an optional friendly name to each of your webhooks. The friendly name is for convenience only and should not be used to programmatically differentiate your webhooks because it does not need to be unique.

You can configure OAuth for your webhook by passing the required values to this endpoint in the oauth_client_id, oauth_client_secret, and oauth_token_url properties. To disable OAuth, pass an empty string to this endpoint for each of the OAuth properties. You may share one OAuth configuration across all your webhooks or create unique credentials for each. See our webhook security documentation for more detailed information about OAuth and the Event Webhook.

Enabling signature verification for your webhook is a separate process and cannot be done with this endpoint. You can use the webhook ID to enable or disable signature verification with the endpoint dedicated for that operation.


Property nameTypeRequiredDescription
Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>

on-behalf-ofstringOptional

The on-behalf-of header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be "account-id" followed by the customer account's ID (e.g., on-behalf-of: account-id <account-id>). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., on-behalf-of: <subuser-username>). See On Behalf Of for more information.

Property nameTypeRequiredDescription
idstringrequired

The ID of the Event Webhook you want to retrieve.

Property nameTypeRequiredDescription
includestringOptional

Use this to include optional fields in the response payload. When this is set to include=account_status_change, the account_status_change field will be part of the response payload and set to false by default. See Update an event webhook for enabling this webhook notification which lets you subscribe to account status change events related to compliance action taken by SendGrid.

Encoding type:application/json
Schema
Property nameTypeRequiredDescriptionChild properties
enabledbooleanOptional

Set this property to true to enable the Event Webhook or false to disable it.


urlstringrequired

Set this property to the URL where you want the Event Webhook to send event data.


group_resubscribebooleanOptional

Set this property to true to receive group resubscribe events. Group resubscribes occur when recipients resubscribe to a specific unsubscribe group by updating their subscription preferences. You must enable Subscription Tracking to receive this type of event.


deliveredbooleanOptional

Set this property to true to receive delivered events. Delivered events occur when a message has been successfully delivered to the receiving server.


group_unsubscribebooleanOptional

Set this property to true to receive group unsubscribe events. Group unsubscribes occur when recipients unsubscribe from a specific unsubscribe group either by direct link or by updating their subscription preferences. You must enable Subscription Tracking to receive this type of event.


spam_reportbooleanOptional

Set this property to true to receive spam report events. Spam reports occur when recipients mark a message as spam.


bouncebooleanOptional

Set this property to true to receive bounce events. A bounce occurs when a receiving server could not or would not accept a message.


deferredbooleanOptional

Set this property to true to receive deferred events. Deferred events occur when a recipient's email server temporarily rejects a message.


unsubscribebooleanOptional

Set this property to true to receive unsubscribe events. Unsubscribes occur when recipients click on a message's subscription management link. You must enable Subscription Tracking to receive this type of event.


processedbooleanOptional

Set this property to true to receive processed events. Processed events occur when a message has been received by Twilio SendGrid and the message is ready to be delivered.


openbooleanOptional

Set this property to true to receive open events. Open events occur when a recipient has opened the HTML message. You must enable Open Tracking to receive this type of event.


clickbooleanOptional

Set this property to true to receive click events. Click events occur when a recipient clicks on a link within the message. You must enable Click Tracking to receive this type of event.


droppedbooleanOptional

Set this property to true to receive dropped events. Dropped events occur when your message is not delivered by Twilio SendGrid. Dropped events are accomponied by a reason property, which indicates why the message was dropped. Reasons for a dropped message include: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota.


friendly_namestring or nullOptional

Optionally set this property to a friendly name for the Event Webhook. A friendly name may be assigned to each of your webhooks to help you differentiate them. The friendly name is for convenience only. You should use the webhook id property for any programmatic tasks.


oauth_client_idstring or nullOptional

Set this property to the OAuth client ID that SendGrid will pass to your OAuth server or service provider to generate an OAuth access token. When passing data in this property, you must also include the oauth_token_url property.


oauth_client_secretstring or nullOptional

Set this property to the OAuth client secret that SendGrid will pass to your OAuth server or service provider to generate an OAuth access token. This secret is needed only once to create an access token. SendGrid will store the secret, allowing you to update your client ID and Token URL without passing the secret to SendGrid again. When passing data in this field, you must also include the oauth_client_id and oauth_token_url properties.


oauth_token_urlstring or nullOptional

Set this property to the URL where SendGrid will send the OAuth client ID and client secret to generate an OAuth access token. This should be your OAuth server or service provider. When passing data in this field, you must also include the oauth_client_id property.

200400404
SchemaExample
Property nameTypeRequiredDescriptionChild properties
enabledboolean

Indicates if the Event Webhook is enabled.


urlstring

The URL where SendGrid will send event data.


account_status_changeboolean

Indicates if the webhook is configured to send account status change events related to compliance action taken by SendGrid.


group_resubscribeboolean

Indicates if the webhook is configured to send group resubscribe events. Group resubscribes occur when recipients resubscribe to a specific unsubscribe group by updating their subscription preferences. You must enable Subscription Tracking to receive this type of event.


deliveredboolean

Indicates if the webhook is configured to send delivered events. Delivered events occur when a message has been successfully delivered to the receiving server.


group_unsubscribeboolean

Indicates if the webhook is configured to send group unsubscribe events. Group unsubscribes occur when recipients unsubscribe from a specific unsubscribe group either by direct link or by updating their subscription preferences. You must enable Subscription Tracking to receive this type of event.


spam_reportboolean

Indicates if the webhook is configured to send spam report events. Spam reports occur when recipients mark a message as spam.


bounceboolean

Indicates if the webhook is configured to send bounce events. A bounce occurs when a receiving server could not or would not accept a message.


deferredboolean

Indicates if the webhook is configured to send deferred events. Deferred events occur when a recipient's email server temporarily rejects a message.


unsubscribeboolean

Indicates if the webhook is configured to send unsubscribe events. Unsubscribes occur when recipients click on a message's subscription management link. You must enable Subscription Tracking to receive this type of event.


processedboolean

Indicates if the webhook is configured to send processed events. Processed events occur when a message has been received by Twilio SendGrid and is ready to be delivered.


openboolean

Indicates if the webhook is configured to send open events. Open events occur when a recipient has opened the HTML message. You must enable Open Tracking to receive this type of event.


clickboolean

Indicates if the webhook is configured to send click events. Click events occur when a recipient clicks on a link within the message. You must enable Click Tracking to receive this type of event.


droppedboolean

Indicates if the webhook is configured to send dropped events. Dropped events occur when your message is not delivered by Twilio SendGrid. Dropped events are accomponied by a reason property, which indicates why the message was dropped. Reasons for a dropped message include: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota.


friendly_namestring or null

An optional friendly name assigned to the Event Webhook to help you differentiate it. The friendly name is for convenience only. You should use the webhook id property for any programmatic tasks.


idstring

A unique string used to identify the webhook. A webhook's ID is generated programmatically and cannot be changed after creation. You can assign a natural language identifier to your webhook using the friendly_name property.


created_datestring<date-time> or null

An ISO 8601 timestamp in UTC timezone when the Event Webhook was created. If a Webhook's created_date is null, it is a legacy Event Webook(link takes you to an external page), which means it is your oldest Webhook.


updated_datestring<date-time>

An ISO 8601 timestamp in UTC timezone when the Event Webhook was last modified.


oauth_client_idstring or null

The OAuth client ID SendGrid sends to your OAuth server or service provider to generate an OAuth access token.


oauth_token_urlstring or null

The URL where SendGrid sends the OAuth client ID and client secret to generate an access token. This should be your OAuth server or service provider.

Update an Event WebhookLink to code sample: Update an Event Webhook
1
const client = require('@sendgrid/client');
2
client.setApiKey(process.env.SENDGRID_API_KEY);
3
4
const id = "ZGkrHSypTsudrGkmdpJJ";
5
const data = {
6
"enabled": true,
7
"url": "https://example.com/webhook-endpoint",
8
"group_resubscribe": true,
9
"delivered": false,
10
"group_unsubscribe": true,
11
"spam_report": true,
12
"bounce": true,
13
"deferred": true,
14
"unsubscribe": true,
15
"processed": false,
16
"open": true,
17
"click": true,
18
"dropped": true,
19
"friendly_name": "Enagement Webhook"
20
};
21
22
const request = {
23
url: `/v3/user/webhooks/event/settings/${id}`,
24
method: 'PATCH',
25
body: data
26
}
27
28
client.request(request)
29
.then(([response, body]) => {
30
console.log(response.statusCode);
31
console.log(response.body);
32
})
33
.catch(error => {
34
console.error(error);
35
});

Subscribe to account status change notifications

subscribe-to-account-status-change-notifications page anchor

After including the account_status_change field in the response payload (as shown in Get All Event Webhooks and Get an Event Webhook), you need to send a PATCH request to subscribe to account_status_change events:

1
curl --location --request PATCH 'https://api.sendgrid.com/v3/user/webhooks/event/settings/ZGkrHSypTsudrGkmdpJJ?include=account_status_change' \
2
--header 'Authorization: Bearer <<YOUR_API_KEY_HERE>>' \
3
--header 'Content-Type: application/json' \
4
--data '{"url": "http://day-charles.info/", "account_status_change": true}'

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.