Twilio SendGrid's Event Webhook will notify a URL via HTTP POST with information about events that occur as your mail is processed. This article covers all you need to know to secure the Event Webhook, allowing you to verify that incoming requests originate from Twilio SendGrid.
For more information about working with the Event Webhook and the data it provides, please see Getting Started with the Event Webhook.
Twilio SendGrid provides two methods for securing the Event Webhook: cryptographic signing and OAuth 2.0. These two security methods are independent of one another and can be used simultaneously.
When using the Signed Event Webhook, Twilio SendGrid will generate a private and public key pair. The private key will be used to generate a signature that is posted to your HTTP webhook in the "X-Twilio-Email-Event-Webhook-Signature"
header.
You can verify the signature with the public key provided. More information is provided in the Verification section of this page.
To enable the Signed Event Webhook and generate a key pair using the SendGrid App:
To disable the Signed Event Webhook, which will delete any existing keys:
Twilio SendGrid provides two Event Webhook API endpoints that allow you to manage signatures. A brief overview of both endpoints is provided below. You can find more at our Event Webhook API Reference.
To enable or disable the Signed Event Webhook, you can pass a PATCH
request to https://api.sendgrid.com/v3/user/webhooks/event/settings/signed
. This endpoint expects a JSON request body with the single required boolean field enabled
.
{
“enabled”: true
}
You can also retrieve your public key by passing a GET
request to https://api.sendgrid.com/v3/user/webhooks/event/settings/signed
. This endpoint accepts no query parameters and will return the string field public_key
containing your current public key.
Twilio SendGrid generates the private and public key pair using the Elliptic Curve Digital Signature Algorithm (ECDSA).
We recommend using a package or library suitable for your language to verify the signature. Libraries are listed below in Sample verification libraries. The general steps required to verify a signature are outlined below with Golang code samples.
When verifying the signature, be aware that we deliver a payload that must be used in its raw bytes form. Transformations from raw bytes to a JSON string may remove characters that were used as part of the generated signature.
"X-Twilio-Email-Event-Webhook-Signature"
HTTP header.// Golang Example
s := http.Request.Header.Get("X-Twilio-Email-Event-Webhook-Signature")
"X-Twilio-Email-Event-Webhook-Timestamp"
HTTP header.// Golang Example
ts := http.Request.Header.Get("X-Twilio-Email-Event-Webhook-Timestamp")
{r value},{s value}
.// Golang Example
signatureBytes, _ := base64.StdEncoding.DecodeString(s)
ecdsaSig := struct {
R *big.Int
S *big.Int
}
asn1.Unmarshal(signatureBytes, &ecdsaSig)
// Golang Example
tsBytes := []byte(ts)
payload, _ := ioutil.ReadAll(http.Request.Body)
h := sha256.New()
h.Write(tsBytes)
h.Write(payload)
hashedPayload := h.Sum(nil)
// Golang Example
// uses https://golang.org/pkg/crypto/ecdsa/ to perform the verification
ecdsa.Verify(publicKey, hashedPayload, ecdsaSig.R, ecdsaSig.S)
The Twilio SendGrid API libraries contain helpers to assist you when verifying the ECDSA signature. The links below will take you to the Event Webhook helper in each library.
OAuth offers an additional and separate way of providing security controls for the Event Webhook. OAuth is an open authorization protocol used to share resources with applications. Rather than sharing your username and password with an application, granting total access to your account, OAuth enables scoped access to your resources. For more on OAuth and how it works, see the OAuth community site.
The Twilio SendGrid Event Webhook uses the Client Credentials OAuth grant type, which is an authorization workflow meant for machine-to-machine communication. This authorization method creates a token that Twilio SendGrid can pass to your app in an Authorization header, allowing you to verify that the request originated from Twilio SendGrid.
OAuth can be confusing. To help illuminate the process, we have provided a description of the setup flow here.
To enable OAuth using the SendGrid App:
Fill the OAuth configuration fields:
Please note, it is your responsibility to verify the access token used in requests to your HTTP POST URL.
To disable OAuth using the SendGrid App:
Twilio SendGrid allows you to manage OAuth setup using the API. A brief overview of enabling, disabling, and testing OAuth; and retrieving your OAuth credentials is provided below. You can find more at our Event Webhook API Reference.
To enable or disable OAuth, you can pass a PATCH
request to https://api.sendgrid.com/v3/user/webhooks/event/settings
.
This endpoint expects a JSON request body. The three optional string fields used to manage OAuth are oauth_client_id
, oauth_client_secret
, and oauth_token_url
.
Passing a request with valid values assigned to these fields will enable OAuth. Passing a request with empty values in these fields will disable OAuth.
{
“oauth_client_id”: “yourclientidstringvalue”,
“oauth_client_secret”: “yourclientsecretstringvalue”,
“oauth_token_url”: “https://your-authorization-service.com”
}
Please note, there are other required fields when making requests to this API endpoint. Please see the API reference for details.
Using the v2 Web API's eventnotify
API call will overwrite any previously configured Event Webhook notification settings, including OAuth 2.0. If your OAuth 2.0 settings are overwitten, please configure them again using either the Mail Settings page or the SendGrid v3 API
You can test your Webhook by passing a POST
request to https://api.sendgrid.com/v3/user/webhooks/event/test
. This request will send a fake event to your HTTP POST URL, which you can use to verify proper functionality. This endpoint expects a JSON request body with a required URL field. To test the OAuth setup, you must include the three optional OAuth fields.
{
“url”: “https://your-http-post-url.com”,
“oauth_client_id”: “yourclientidstringvalue”,
“oauth_client_secret”: “yourclientsecretstringvalue”,
“oauth_token_url”: “https://your-authorization-service.com”
}
To retrieve your OAuth credentials, pass a GET
request to https://api.sendgrid.com/v3/user/webhooks/event/settings
. You do not need to pass any query parameters to this endpoint. Note that only the oauth_client_id
and oauth_token_url
will be returned. The oauth_client_secret
will not be provided for security reasons.
Twilio SendGrid currently supports two helper libraries for working with the Event Webhook’s security features: Golang and Java. We have also provided a Java code example on GitHub.
Now that you know how to secure the Event Webhook, you can begin using your event data to better understand your email. To finish setting up the Webhook, see Getting Started with the Event Webhook or jump right into the Event Webhook Reference.
Let us know how we’re doing! Please rate this page:
If you require immediate assistance from Twilio SendGrid, please contact our support team. If you’ve spotted a documentation problem, please open a GitHub Issue!
Please note, we cannot resolve account and login issues reported on GitHub. Contact support for account assistance.
Thanks for helping us improve our docs!