# Create an Event Webhook ## 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. ## Data storage Currently, data staged to be posted through the webhooks is stored in the US. ## Operation overview ```json {"path":"https://api.sendgrid.com/v3/user/webhooks/event/settings","method":"post","servers":[{"url":"https://api.sendgrid.com","description":"for global users and subusers"},{"url":"https://api.eu.sendgrid.com","description":"for EU regional subusers"}]} ``` **This endpoint allows you to create a new Event Webhook.** When creating a webhook, you will provide a URL where you want the webhook to send POST requests, and you will select which events you want to receive in those request. See the [**Event Webhook Reference**](/docs/sendgrid/for-developers/tracking-events/event#delivery-events) for details about each event type. ### Webhook identifiers When your webhook is succesfully created, you will receive a webhook `id` in the response returned by this endpoint. You can use that ID to [update the webhook's settings](/docs/sendgrid/api-reference/webhooks/update-an-event-webhook), [delete the webhook](/docs/sendgrid/api-reference/webhooks/delete-an-event-webhook), [enable or disable signature verification for the webhook](/docs/sendgrid/api-reference/webhooks/toggle-signature-verification-for-an-event-webhook), and, if signature verification is enabled, [retrieve the webhook's public key](/docs/sendgrid/api-reference/webhooks/get-signed-event-webhooks-public-key). You may also 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. Use the webhook ID to reliably differentiate among your webhooks. ### OAuth You can optionally configure OAuth verification for your webhook at the time of creation by passing the appropriate values in the `oauth_client_id`, `oauth_client_secret`, and `oauth_token_url` properties. You can enable or disable OAuth for the webhook after creation with the [**Update an Event Webhook**](/docs/sendgrid/api-reference/webhooks/update-an-event-webhook) operation. You may share one OAuth configuration across all your webhooks or create unique credentials for each. See our [webhook security documentation](/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-security-features#oauth-20) for details about OAuth and the Event Webhook. ### Signature verification Enabling signature verification for your webhook is a separate process and cannot be done at the time of creation with this endpoint. You can use the webhook ID to [enable or disable signature verification with the endpoint dedicated for that operation](/docs/sendgrid/api-reference/webhooks/toggle-signature-verification-for-an-event-webhook). ## Operation details ### Authentication API Key ### Headers ```json [{"in":"header","name":"Authorization","required":true,"default":"Bearer <>","schema":{"type":"string"}},{"name":"on-behalf-of","in":"header","description":"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 `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). See [**On Behalf Of**](/docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.","required":false,"schema":{"type":"string"},"refName":"#/components/parameters/OnBehalfOf","modelName":"__components_parameters_OnBehalfOf"}] ``` ### Request body ```json {"schema":{"title":"Create and Update Event Webhook Request Body","type":"object","required":["url"],"refName":"EventWebhookRequest","modelName":"EventWebhookRequest","properties":{"enabled":{"type":"boolean","description":"Set this property to `true` to enable the Event Webhook or `false` to disable it."},"url":{"type":"string","description":"Set this property to the URL where you want the Event Webhook to send event data."},"group_resubscribe":{"type":"boolean","description":"Set this property to `true` to receive group resubscribe events. Group resubscribes occur when recipients resubscribe to a specific [unsubscribe group](/docs/sendgrid/ui/sending-email/create-and-manage-unsubscribe-groups) by updating their subscription preferences. You must [enable Subscription Tracking](/docs/sendgrid/ui/account-and-settings/tracking#subscription-tracking) to receive this type of event."},"delivered":{"type":"boolean","description":"Set this property to `true` to receive delivered events. Delivered events occur when a message has been successfully delivered to the receiving server."},"group_unsubscribe":{"type":"boolean","description":"Set this property to `true` to receive group unsubscribe events. Group unsubscribes occur when recipients unsubscribe from a specific [unsubscribe group](/docs/sendgrid/ui/sending-email/create-and-manage-unsubscribe-groups) either by direct link or by updating their subscription preferences. You must [enable Subscription Tracking](/docs/sendgrid/ui/account-and-settings/tracking#subscription-tracking) to receive this type of event."},"spam_report":{"type":"boolean","description":"Set this property to `true` to receive spam report events. Spam reports occur when recipients mark a message as spam."},"bounce":{"type":"boolean","description":"Set this property to `true` to receive bounce events. A bounce occurs when a receiving server could not or would not accept a message."},"deferred":{"type":"boolean","description":"Set this property to `true` to receive deferred events. Deferred events occur when a recipient's email server temporarily rejects a message."},"unsubscribe":{"type":"boolean","description":"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](/docs/sendgrid/ui/account-and-settings/tracking#subscription-tracking) to receive this type of event."},"processed":{"type":"boolean","description":"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."},"open":{"type":"boolean","description":"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](/docs/sendgrid/ui/account-and-settings/tracking#open-tracking) to receive this type of event."},"click":{"type":"boolean","description":"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](/docs/sendgrid/ui/account-and-settings/tracking#click-tracking) to receive this type of event."},"dropped":{"type":"boolean","description":"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_name":{"type":"string","description":"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.","nullable":true},"oauth_client_id":{"type":"string","description":"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.","nullable":true},"oauth_client_secret":{"type":"string","description":"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.","nullable":true},"oauth_token_url":{"type":"string","description":"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.","nullable":true}}},"examples":{"Request With OAuth Configured":{"summary":"POST request body to create an Event Webhook with OAuth configured.","value":{"enabled":true,"url":"https://example.com/webhook-endpoint","group_resubscribe":true,"delivered":false,"group_unsubscribe":true,"spam_report":true,"bounce":true,"deferred":true,"unsubscribe":true,"processed":false,"open":true,"click":true,"dropped":true,"friendly_name":"Engagement Webhook","oauth_client_id":"a835e7210bbb47edbfa71bdfc909b2d7","oauth_client_secret":"335a9b0c65324fd2a62e2953d4b158","oauth_token_url":"https://oauthservice.example.com"}},"Request Without OAuth Configured":{"summary":"POST request body to create an Event Webhook without OAuth configured.","value":{"enabled":true,"url":"https://example.com/webhook-endpoint","group_resubscribe":true,"delivered":false,"group_unsubscribe":true,"spam_report":true,"bounce":true,"deferred":true,"unsubscribe":true,"processed":false,"open":true,"click":true,"dropped":true,"friendly_name":"Engagement Webhook"}}},"encodingType":"application/json"} ``` ### Responses ```json [{"responseCode":"201","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","refName":"EventWebhookUnsignedResponse","modelName":"EventWebhookUnsignedResponse","properties":{"enabled":{"type":"boolean","description":"Indicates if the Event Webhook is enabled."},"url":{"type":"string","description":"The URL where SendGrid will send event data."},"account_status_change":{"type":"boolean","description":"Indicates if the webhook is configured to send account status change events related to compliance action taken by SendGrid."},"group_resubscribe":{"type":"boolean","description":"Indicates if the webhook is configured to send group resubscribe events. Group resubscribes occur when recipients resubscribe to a specific [unsubscribe group](/docs/sendgrid/ui/sending-email/create-and-manage-unsubscribe-groups) by updating their subscription preferences. You must [enable Subscription Tracking](/docs/sendgrid/ui/account-and-settings/tracking#subscription-tracking) to receive this type of event."},"delivered":{"type":"boolean","description":"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_unsubscribe":{"type":"boolean","description":"Indicates if the webhook is configured to send group unsubscribe events. Group unsubscribes occur when recipients unsubscribe from a specific [unsubscribe group](/docs/sendgrid/ui/sending-email/create-and-manage-unsubscribe-groups) either by direct link or by updating their subscription preferences. You must [enable Subscription Tracking](/docs/sendgrid/ui/account-and-settings/tracking#subscription-tracking) to receive this type of event."},"spam_report":{"type":"boolean","description":"Indicates if the webhook is configured to send spam report events. Spam reports occur when recipients mark a message as spam."},"bounce":{"type":"boolean","description":"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."},"deferred":{"type":"boolean","description":"Indicates if the webhook is configured to send deferred events. Deferred events occur when a recipient's email server temporarily rejects a message."},"unsubscribe":{"type":"boolean","description":"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](/docs/sendgrid/ui/account-and-settings/tracking#subscription-tracking) to receive this type of event."},"processed":{"type":"boolean","description":"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."},"open":{"type":"boolean","description":"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](/docs/sendgrid/ui/account-and-settings/tracking#open-tracking) to receive this type of event."},"click":{"type":"boolean","description":"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](/docs/sendgrid/ui/account-and-settings/tracking#click-tracking) to receive this type of event."},"dropped":{"type":"boolean","description":"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_name":{"type":"string","description":"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.","nullable":true},"id":{"type":"string","description":"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_date":{"type":"string","description":"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](https://www.twilio.com/en-us/changelog/event-webhooks), which means it is your oldest Webhook.","format":"date-time","nullable":true},"updated_date":{"type":"string","description":"An ISO 8601 timestamp in UTC timezone when the Event Webhook was last modified.","format":"date-time"},"oauth_client_id":{"type":"string","description":"The OAuth client ID SendGrid sends to your OAuth server or service provider to generate an OAuth access token.","nullable":true},"oauth_token_url":{"type":"string","description":"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.","nullable":true}}},"examples":{"Success With OAuth Configured":{"summary":"Success response body for a webhook with OAuth configured.","value":{"enabled":true,"url":"https://example.com/webhook-endpoint","group_resubscribe":true,"delivered":false,"group_unsubscribe":true,"spam_report":true,"bounce":true,"deferred":true,"unsubscribe":true,"processed":false,"open":true,"click":true,"dropped":true,"friendly_name":"Engagement Webhook","oauth_client_id":"a835e7210bbb47edbfa71bdfc909b2d7","oauth_token_url":"https://oauthservice.example.com","id":"77d4a5da-7015-11ed-a1eb-0242ac120002","created_date":"2023-01-01T12:00:00Z","updated_date":"2023-02-15T10:00:00Z"}}}}}}},{"responseCode":"400","schema":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The ID of a Webhook that exists on your account that is already configured to send events to the endpoint URL you provided."},"message":{"type":"string","description":"Error message."},"url":{"type":"string","description":"The URL that is already configured as a Webhook endpoint for one of your existing Webhooks."}}}}}},"examples":{"Bad URL":{"value":{"errors":[{"message":"'https://example.com' is not a valid url"}]}},"Exists":{"value":{"errors":[{"id":"123abc456def890ghi","message":"Webhook at 'https://example.com' already exists. Please provide a unique URL.","url":"https://example.com"}]}},"Max webhooks reached":{"value":{"errors":[{"message":"You have reached the maximum number of webhooks per your current billing plan."}]}}}}}}}] ``` Create an Event Webhook ```js const client = require("@sendgrid/client"); client.setApiKey(process.env.SENDGRID_API_KEY); const data = { enabled: true, url: "https://example.com/webhook-endpoint", group_resubscribe: true, delivered: false, group_unsubscribe: true, spam_report: true, bounce: true, deferred: true, unsubscribe: true, processed: false, open: true, click: true, dropped: true, friendly_name: "Engagement Webhook", }; const request = { url: `/v3/user/webhooks/event/settings`, method: "POST", body: data, }; client .request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) .catch((error) => { console.error(error); }); ``` ```python import os from sendgrid import SendGridAPIClient sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY")) data = { "enabled": True, "url": "https://example.com/webhook-endpoint", "group_resubscribe": True, "delivered": False, "group_unsubscribe": True, "spam_report": True, "bounce": True, "deferred": True, "unsubscribe": True, "processed": False, "open": True, "click": True, "dropped": True, "friendly_name": "Engagement Webhook", } response = sg.client.user.webhooks.event.settings.post(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using SendGrid; public class Program { public static async Task Main() { string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY"); var client = new SendGridClient(apiKey); var data = @"{ ""enabled"": true, ""url"": ""https://example.com/webhook-endpoint"", ""group_resubscribe"": true, ""delivered"": false, ""group_unsubscribe"": true, ""spam_report"": true, ""bounce"": true, ""deferred"": true, ""unsubscribe"": true, ""processed"": false, ""open"": true, ""click"": true, ""dropped"": true, ""friendly_name"": ""Engagement Webhook"" }"; var response = await client.RequestAsync( method: SendGridClient.Method.POST, urlPath: "user/webhooks/event/settings", requestBody: data); Console.WriteLine(response.StatusCode); Console.WriteLine(response.Body.ReadAsStringAsync().Result); Console.WriteLine(response.Headers.ToString()); } } ``` ```java import com.sendgrid.*; import java.io.IOException; import org.json.JSONObject; import java.util.HashMap; public class Example { public static void main(String[] args) throws IOException { try { SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY")); Request request = new Request(); request.setMethod(Method.POST); request.setEndpoint("/user/webhooks/event/settings"); request.setBody(new JSONObject(new HashMap() { { put("enabled", true); put("url", "https://example.com/webhook-endpoint"); put("group_resubscribe", true); put("delivered", false); put("group_unsubscribe", true); put("spam_report", true); put("bounce", true); put("deferred", true); put("unsubscribe", true); put("processed", false); put("open", true); put("click", true); put("dropped", true); put("friendly_name", "Engagement Webhook"); } }).toString()); Response response = sg.api(request); System.out.println(response.getStatusCode()); System.out.println(response.getBody()); System.out.println(response.getHeaders()); } catch (IOException ex) { throw ex; } } } ``` ```go package main import ( "fmt" "github.com/sendgrid/sendgrid-go" "os" ) func main() { apiKey := os.Getenv("SENDGRID_API_KEY") host := "https://api.sendgrid.com" request := sendgrid.GetRequest(apiKey, "/v3/user/webhooks/event/settings", host) request.Method = "POST" request.Body = []byte(`{ "enabled": true, "url": "https://example.com/webhook-endpoint", "group_resubscribe": true, "delivered": false, "group_unsubscribe": true, "spam_report": true, "bounce": true, "deferred": true, "unsubscribe": true, "processed": false, "open": true, "click": true, "dropped": true, "friendly_name": "Engagement Webhook" }`) response, err := sendgrid.API(request) if err != nil { fmt.Println(err.Error()) os.Exit(1) } else { fmt.Println(response.StatusCode) fmt.Println(response.Body) fmt.Println(response.Headers) } } ``` ```php /sendgrid-php.php'; $apiKey = getenv("SENDGRID_API_KEY"); $sg = new \SendGrid($apiKey); $request_body = json_decode('{ "enabled": true, "url": "https://example.com/webhook-endpoint", "group_resubscribe": true, "delivered": false, "group_unsubscribe": true, "spam_report": true, "bounce": true, "deferred": true, "unsubscribe": true, "processed": false, "open": true, "click": true, "dropped": true, "friendly_name": "Engagement Webhook" }'); try { $response = $sg->client ->user() ->webhooks() ->event() ->settings() ->post($request_body); print $response->statusCode() . "\n"; print_r($response->headers()); print $response->body() . "\n"; } catch (Exception $ex) { echo "Caught exception: " . $ex->getMessage(); } ``` ```ruby require 'sendgrid-ruby' include SendGrid sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']) data = JSON.parse('{ "enabled": true, "url": "https://example.com/webhook-endpoint", "group_resubscribe": true, "delivered": false, "group_unsubscribe": true, "spam_report": true, "bounce": true, "deferred": true, "unsubscribe": true, "processed": false, "open": true, "click": true, "dropped": true, "friendly_name": "Engagement Webhook" }') response = sg.client.user.webhooks.event.settings.post(request_body: data) puts response.status_code puts response.headers puts response.body ``` ```bash curl -X POST "https://api.sendgrid.com/v3/user/webhooks/event/settings" \ --header "Authorization: Bearer $SENDGRID_API_KEY" \ --header "Content-Type: application/json" \ --data '{"enabled": true, "url": "https://example.com/webhook-endpoint", "group_resubscribe": true, "delivered": false, "group_unsubscribe": true, "spam_report": true, "bounce": true, "deferred": true, "unsubscribe": true, "processed": false, "open": true, "click": true, "dropped": true, "friendly_name": "Engagement Webhook"}' ```