Getting Started with the Event Webhook Security Features

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 signature verification and generate a key pair:

1. Navigate to Settings > Mail Settings in the sidebar navigation.

2. Under Webhook Settings, click Event Webhooks:

   1. If you have Webhooks set up already, you will see them displayed in a table. You can edit a Webhook by following the "Edit an Event Webhook" instructions in the Twilio SendGrid Event Webhook Overview.
   2. If you have not set up any Webhooks, you can create one by following the "Add an Event Webhook" instructions in the Getting Started with the Event Webhook documentation. For new Webhooks, you must enter mandatory information such as the Post URL and Actions to be posted before you can enable signature verification.

3. Once you have begun creating or editing a Webhook, you will manage its security features in the Security features section of the dialog that opens.

4. Scroll to Security features and toggle Enable Signed Event Webhook. Please note, you must click Save in order to generate a verification key and enable signature verification. If you click Test Integration before clicking Save, signature verification will not be tested because the key pair is only generated once the Webhook is saved.

Expand image

5. Once you click Save, the dialog will close. To confirm that signature verification is enabled, navigate back to the dialog by clicking the cog and then clicking Edit. Now you will see the Signature verification setting is enabled and your public verification key is displayed.
6. You can now copy the public key and use it to verify that requests are coming from Twilio SendGrid.

Expand image

Expand image

To disable signature verification, which will delete the Webhook's existing key pair:

1. Edit the Webhook by following the "Edit an Event Webhook" instructions in the Twilio SendGrid Event Webhook Overview documentation.
2. When a signature exists, the Webhook's configuration dialog will show a toggle with Enable Signed Event Webhook as enabled (blue).
3. Toggle Enable Signed Event Webhook to disable the feature (gray). Your key pair will not be deleted until you click Save.
4. Click Save to delete your existing key pair for the Webhook.

Expand image

You can also manage signature verification for the Event Webhook using SendGrid's API. See the Event Webhook API reference for more information.

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 the "Sample verification libraries" section of this page. The general steps required to verify a signature are outlined below with Go code samples.

1. Initiate the GET request by including the parameters listed (Headers and Responses) on the Get an Event Webhook documentation.
2. Get the signature from the "X-Twilio-Email-Event-Webhook-Signature" HTTP header.

1
// Golang Example
2
s := http.Request.Header.Get("X-Twilio-Email-Event-Webhook-Signature")

2. Get the timestamp from the "X-Twilio-Email-Event-Webhook-Timestamp" HTTP header.

1
// Golang Example
2
ts := http.Request.Header.Get("X-Twilio-Email-Event-Webhook-Timestamp")

3. Decode the Base64 encoded signature. Then perform an ASN.1 unmarshal of the decoded signature into a string. This string will be in the form of {r value},{s value}.

1
// Golang Example
2
signatureBytes, _ := base64.StdEncoding.DecodeString(s)
3
ecdsaSig := struct {
4
R *big.Int
5
S *big.Int
6
}
7

8
asn1.Unmarshal(signatureBytes, &ecdsaSig)

4. Generate a sha256 hash of the timestamp + payload (use raw bytes).

1
// Golang Example
2
tsBytes := []byte(ts)
3
payload, _ := ioutil.ReadAll(http.Request.Body)
4
h := sha256.New()
5
h.Write(tsBytes)
6
h.Write(payload)
7
hashedPayload := h.Sum(nil)

5. Verify the signature.

1
// Golang Example
2
// uses https://golang.org/pkg/crypto/ecdsa/ to perform the verification
3
ecdsa.Verify(publicKey, hashedPayload, ecdsaSig.R, ecdsaSig.S)

6. Again, the simplest way to verify the signature is to use a package or library that will abstract away this process into a helper method or function.

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.

• C# Event Webhook Helper
• Go Event Webhook Helper
• Java Event Webhook Helper
• Node.js Event Webhook Helper
• PHP Event Webhook Helper
• Python Event Webhook Helper
• Ruby Event Webhook Helper

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.

1. You, the customer, have an app that provides an HTTP webhook endpoint URL. You want the Twilio SendGrid Event Webhook to make POST requests to this URL. To ensure that the requests you receive are actually from Twilio SendGrid, you implement OAuth.
2. This means you are responsible for generating a Client ID and Client Secret. You must also provide two URLs, the HTTP POST URL endpoint for your app and a URL to an authorization server or OAuth service.
3. When you give Twilio SendGrid all of this information, it will pass the Client ID and Client Secret to the Token URL (your authorization server/OAuth service). The authorization server will then use the Client ID and Client Secret to generate an access token. This token is sent back to Twilio SendGrid.
4. The access token is meaningless to SendGrid. It acts only as a key to pass back to your app at the HTTP POST URL endpoint. This will be done in an Authorization header.
5. Because this access token is shared among only your app, the authorization server, and SendGrid, you can trust requests delivered with the token are from a trusted source.
6. You can verify the access token is legitimate by checking with the authorization server that created it.

Expand image

To enable OAuth 2.0:

1. Navigate to Settings > Mail Settings in the sidebar navigation.

2. Under Webhook Settings, click Event Webhooks:

   1. If you have Webhooks set up already, you will see them displayed in a table. You can edit a Webhook by following the "Edit an Event Webhook" instructions in the Twilio SendGrid Event Webhook Overview documentation.
   2. If you have not set up any Webhooks, you can create one by following the "Add an Event Webhook" instructions in the Getting Started with the Event Webhook documentation. For new Webhooks, you must enter mandatory information such as the Post URL and Actions to be posted before you can enable and configure OAuth verification.

3. Once you have begun creating or editing a Webhook, you will manage its security features in the Security features section of the dialog that opens. Unlike signature verification, OAuth verification can be completed without first saving the Webhook.

4. Scroll to Security features and toggle Enable OAuth to reveal Client ID, Secret Token, and Token URL fields.

Expand image

5. Fill the OAuth configuration fields:
   1. Client ID: Required to generate an authorization token.
   2. Client Secret: Required to generate an authorization token. This secret is needed only once to create an access token. SendGrid will store this secret, allowing you to update your Client ID and Token URL without passing the secret to SendGrid again.
   3. Token URL: The URL where Twilio SendGrid should deliver the Client ID and Client Secret in order to create an access token. This URL should route to your own authorization server or an OAuth service such as Okta.
6. With the above steps completed, requests to your Post URL by Twilio SendGrid will contain the access token in an Authorization header. You can now use this token to verify the requests using your OAuth service or authorization server.

To disable OAuth 2.0:

1. Edit the Webhook by following the "Edit an Event Webhook" instructions in the Twilio SendGrid Event Webhook Overview documentation.
2. When OAuth is enabled, the Webhook's configuration dialog will show a toggle with Enable OAuth as enabled (blue).
3. Toggle Enable OAuth to disable the feature (gray).
4. Click Save.
5. The requests to your HTTP POST URL by Twilio SendGrid will no longer contain an access token.

Twilio SendGrid allows you to manage OAuth setup using the API. See the Event Webhook API reference for more information.

Once you have established an OAuth Access Token per the above directions, SendGrid will cache that token so that it can be used in any further webhook requests without each time requesting that token again from your OAuth service.

Upon receiving a webhook request with an invalid or expired token, your webhook needs to return a status code of 4xx (typically 400, 401 or 403) and the body payload must contain one of the following strings:

"invalid_request", "invalid_token", "insufficient_scope".

More specifically, SendGrid follows RFC 6750, which defines the error codes as follows:

invalid_request

invalid_token

insufficient_scope

Upon receiving any of these error codes from your webhook, SendGrid will request a new OAuth token from your OAuth service and retry the webhook.

Now that you know how to secure the Event Webhook, you can begin using your event data to better understand your email. See the Event Webhook Reference for more information about the data it provides.

• Getting Started with the Event Webhook
• Twilio SendGrid Event Webhook Overview
• Event Webhook reference
• Event Webhook API
• An Event Webhook case study