Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Get All Event Webhooks



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.

Event types

event-types page anchor

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.


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.

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.

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

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.


Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>

on-behalf-ofstring

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.

includestring

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.

200

Success

SchemaExample
max_allowednumber

The maximum number of Event Webhooks you can have enabled under your current Twilio SendGrid plan. See the Twilio SendGrid pricing page(link takes you to an external 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.

Get All Event Webhooks

get-all-event-webhooks page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
curl

_18
const client = require('@sendgrid/client');
_18
client.setApiKey(process.env.SENDGRID_API_KEY);
_18
_18
_18
const request = {
_18
url: `/v3/user/webhooks/event/settings/all`,
_18
method: 'GET',
_18
_18
}
_18
_18
client.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

include-account_status_change-in-the-response-payload page anchor

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
C#
Java
Go
PHP
Ruby
curl

_21
const client = require('@sendgrid/client');
_21
client.setApiKey(process.env.SENDGRID_API_KEY);
_21
_21
const queryParams = {
_21
"include": "account_status_change"
_21
};
_21
_21
const request = {
_21
url: `/v3/user/webhooks/event/settings/all`,
_21
method: 'GET',
_21
qs: queryParams
_21
}
_21
_21
client.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
});


Rate this page: