Skip to content Skip to navigation Skip to topbar

On this page

Get All Event Webhooks

API Overview

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.

Event types

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.

Operation overview

GET/v3/user/webhooks/event/settings/all

Base url: https://api.sendgrid.com

This endpoint allows you to retrieve all of your Event Webhooks.

Each webhook will be returned as an object in the webhooks array with the webhook's configuration details and ID. You can use a webhook's ID to update the webhook's settings, delete the webhook, enable or disable signature verification for the webhook, and, if signature verification is enabled, retrieve the webhook's public key when signature verification is enabled.

Event settings

Each webhook's settings determine which events will be included in the POST request by the webhook and the URL where the request will be sent. See the Event Webhook Reference for details about each event type.

Signature verification

The public_key property will be returned only for webhooks with signature verification enabled.

OAuth

You may share one OAuth configuration across all your webhooks or create unique credentials for each. The OAuth properties will be returned only for webhooks with OAuth configured.

Operation details

Authentication

API Key

Headers

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.

Query string

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.

Responses

200

Success

SchemaExample

Property nameTypeRequiredDescriptionChild properties

max_allowednumber

The maximum number of Event Webhooks you can have enabled under your current Twilio SendGrid plan. See the Twilio SendGrid pricing page for more information about the features available with each plan.

webhooksarray[object]

An array of Event Webhook objects. Each object represents one of your webhooks and contains its configuration settings, including which events it is set to send in the POST request, the URL where it will send those events, and the webhook's ID.

Show child properties for webhooks

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, 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.

public_keystring

The public key you can use to verify the SendGrid signature.

Get All Event Webhooks

Node.js

Python

Java

PHP

Ruby

curl


_18const client = require('@sendgrid/client');
_18client.setApiKey(process.env.SENDGRID_API_KEY);
_18
_18
_18const request = {
_18  url: `/v3/user/webhooks/event/settings/all`,
_18  method: 'GET',
_18  
_18}
_18
_18client.request(request)
_18  .then(([response, body]) => {
_18    console.log(response.statusCode);
_18    console.log(response.body);
_18  })
_18  .catch(error => {
_18    console.error(error);
_18  });

Include account_status_change in the response payload

This will include the field in the response payload. See Update an Event Webhook (Subscribe to account status change notifications section) for subscribing to these notifications.

Node.js

Python

Java

PHP

Ruby

curl


_21const client = require('@sendgrid/client');
_21client.setApiKey(process.env.SENDGRID_API_KEY);
_21
_21const queryParams = {
_21  "include": "account_status_change"
_21};
_21
_21const request = {
_21  url: `/v3/user/webhooks/event/settings/all`,
_21  method: 'GET',
_21  qs: queryParams
_21}
_21
_21client.request(request)
_21  .then(([response, body]) => {
_21    console.log(response.statusCode);
_21    console.log(response.body);
_21  })
_21  .catch(error => {
_21    console.error(error);
_21  });