openapi: 3.1.0
info:
title: Twilio SendGrid Provisioning Account Event Webhook API
summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts.
description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.
You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
termsOfService: https://www.twilio.com/legal/tos
contact:
name: Twilio SendGrid Support
url: https://support.sendgrid.com/hc/en-us
license:
name: MIT
url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
version: 1.0.0
x-sendgrid:
libraryPackage: account_provisioning
servers:
- url: https://api.sendgrid.com
description: for global users and subusers
- url: https://api.eu.sendgrid.com
description: for EU regional subusers
security:
- BearerAuth: []
tags:
- name: Event Webhook
description: Twilio SendGrid Event Webhook API
paths:
/v3/user/webhooks/event/settings:
post:
operationId: CreateEventWebhook
summary: Create a new Event Webhook
tags:
- Event Webhook
description: '**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**](https://docs.sendgrid.com/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](https://docs.sendgrid.com/api-reference/webhooks/update-an-event-webhook), [delete the webhook](https://docs.sendgrid.com/api-reference/webhooks/delete-an-event-webhook), [enable or disable signature verification for the webhook](https://docs.sendgrid.com/api-reference/webhooks/toggle-signature-verification-for-an-event-webhook), and, if signature verification is enabled, [retrieve the webhook''s public key](https://docs.sendgrid.com/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**](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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](https://docs.sendgrid.com/api-reference/webhooks/toggle-signature-verification-for-an-event-webhook).'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EventWebhookRequest'
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
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EventWebhookUnsignedResponse'
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'
'400':
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.
/v3/user/webhooks/event/settings/all:
get:
operationId: ListEventWebhook
summary: Retrieve all of your Event Webhooks.
tags:
- Event Webhook
description: '**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](https://docs.sendgrid.com/api-reference/webhooks/update-an-event-webhook), [delete the webhook](https://docs.sendgrid.com/api-reference/webhooks/delete-an-event-webhook), [enable or disable signature verification for the webhook](https://docs.sendgrid.com/api-reference/webhooks/toggle-signature-verification-for-an-event-webhook), and, if signature verification is enabled, [retrieve the webhook''s public key](https://docs.sendgrid.com/api-reference/webhooks/get-signed-event-webhooks-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**](https://docs.sendgrid.com/for-developers/tracking-events/event#delivery-events) 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.'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/Include'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EventWebhookAllResponse'
examples:
Two Webhooks:
value:
max_allowed: 5
webhooks:
- enabled: true
url: https://emailengagment.example.com
group_resubscribe: true
delivered: true
group_unsubscribe: true
spam_report: true
bounce: true
deferred: true
unsubscribe: true
processed: false
open: true
click: true
dropped: true
friendly_name: Engagment Webhook
id: 77d4a5da-7015-11ed-a1eb-0242ac120002
oauth_client_id: a835e7210bbb47edbfa71bdfc909b2d7
oauth_token_url: https://oauthservice.example.com
public_key: 123publickeyabc
created_date: '2023-01-01T12:00:00Z'
updated_date: '2023-02-15T10:00:00Z'
- enabled: true
url: https://emaildelivery.example.com
group_resubscribe: false
delivered: true
group_unsubscribe: false
spam_report: false
bounce: true
deferred: true
unsubscribe: false
processed: true
open: false
click: false
dropped: true
friendly_name: Delivery Webhook
id: 77d4a5da-7015-11ed-a1eb-0242ac120003
oauth_client_id: a835e7210bbb47edbfa71bdfc909b2d7
oauth_token_url: https://oauthservice.example.com
public_key: 123publickeydef
created_date: '2023-01-01T12:00:00Z'
updated_date: '2023-02-15T10:00:00Z'
Zero Webhooks:
value:
max_allowed: 5
webhooks:
- {}
/v3/user/webhooks/event/settings/signed/{id}:
get:
operationId: GetSignedEventWebhook
summary: Get Signed Event Webhook's Public Key
tags:
- Event Webhook
description: '**This endpoint allows you to retrieve the public key for a single Event Webhook by ID.**
If you do not pass a webhook ID to this endpoint, it will return the public key for your oldest webhook by `created_date`. This means the default key returned by this endpoint when no ID is provided will be for the first webhook you created. This functionality allows customers who do not have multiple webhooks to use this endpoint to retrieve their only webhook''s public key, even if they do not supply an ID. If you have multiple webhooks, you can retrieve their IDs using the [**Get All Event Webhooks**](https://docs.sendgrid.com/api-reference/webhooks/get-all-event-webhooks) endpoint.
Once you have enabled signature verification for a webhook, you will need the public key provided to verify the signatures on requests coming from Twilio SendGrid. You can use the webhook ID to [enable or disable signature verification with the endpoint dedicated for that operation](https://docs.sendgrid.com/api-reference/webhooks/toggle-signature-verification-for-an-event-webhook).
For more information about cryptographically signing the Event Webhook, see [**Getting Started with the Event Webhook Security Features**](https://sendgrid.com/docs/for-developers/tracking-events/getting-started-event-webhook-security-features).'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/RequestId'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
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.
public_key:
type: string
description: The public key you can use to verify the Twilio SendGrid signature.
examples:
No ID:
value:
id: ''
public_key: 123publickeyabc
ID:
value:
id: 77d4a5da-7015-11ed-a1eb-0242ac120002
public_key: 123publickeyabc
'404':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
description: Error message.
examples:
Not found:
value:
errors:
- message: Invalid id provided.
patch:
operationId: UpdateSignedEventWebhook
summary: Toggle signature verification for a single Event Webhook by ID
tags:
- Event Webhook
description: '**This endpoint allows you to enable or disable signature verification for a single Event Webhook by ID.**
If you do not pass a webhook ID to this endpoint, it will enable signature verification for your oldest webhook by `created_date`. This means the default webhook operated on by this endpoint when no ID is provided will be the first one you created. This functionality allows customers who do not have multiple webhooks to enable or disable signature verifiction for their only webhook, even if they do not supply an ID. If you have multiple webhooks, you can retrieve their IDs using the [**Get All Event Webhooks**](https://docs.sendgrid.com/api-reference/webhooks/get-all-event-webhooks) endpoint.
This endpoint accepts a single boolean request property, `enabled`, that can be set `true` or `false` to enable or disable signature verification. This endpoint will return the public key required to verify Twilio SendGrid signatures if it is enabled or an empty string if signing is disabled. You can also retrieve your public key using the [**Get an Event Webhook''s Public Key**](https://docs.sendgrid.com/api-reference/webhooks/get-signed-event-webhooks-public-key) endpoint.
For more information about cryptographically signing the Event Webhook, see [**Getting Started with the Event Webhook Security Features**](https://sendgrid.com/docs/for-developers/tracking-events/getting-started-event-webhook-security-features).'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/RequestId'
requestBody:
content:
application/json:
schema:
type: object
properties:
enabled:
type: boolean
description: Enable or disable the webhook by setting this property to `true` or `false`, respectively.
required:
- enabled
examples:
example1:
value:
enabled: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
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.
public_key:
type: string
description: The public key you can use to verify the Twilio SendGrid signature.
examples:
Enabled:
value:
id: 77d4a5da-7015-11ed-a1eb-0242ac120002
public_key: 123publickeyabc
Disabled:
value:
id: 77d4a5da-7015-11ed-a1eb-0242ac120002
public_key: ''
'404':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
description: Error message.
examples:
Not found:
value:
errors:
- message: Invalid id provided.
/v3/user/webhooks/event/test:
post:
operationId: TestEventWebhook
summary: Test an Event Webhook's settings
tags:
- Event Webhook
description: '**This endpoint allows you to test an Event Webhook.**
Retry logic for this endpoint differs from other endpoints, which use a rolling 24-hour retry.
This endpoint will make a POST request with a fake event notification to a URL you provide. This allows you to verify that you have properly configured the webhook before sending real data to your URL.
### Test OAuth configuration
To test your OAuth configuration, you must include the necessary OAuth properties: `oauth_client_id`, `oauth_client_secret`, and `oauth_token_url`.
If the webhook you are testing already has OAuth credentials saved, you will provide only the `oauth_client_id` and `oauth_token_url`—we will pull the secret for you. If you are testing a new set of OAuth credentials that have not been saved with SendGrid, you must provide all three property values.
You can retrieve a previously saved `oauth_client_id` and `oauth_token_url` from the [**Get an Event Webhook**](https://docs.sendgrid.com/api-reference/webhooks/get-an-event-webhook) endpoint; however, for security reasons, SendGrid will not provide your `oauth_client_secret`.'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EventWebhookTestRequest'
responses:
'204':
description: No Content
/v3/user/webhooks/event/settings/{id}:
get:
operationId: GetEventWebhook
summary: Get the settings for a single Event Webhook.
tags:
- Event Webhook
description: '**This endpoint allows you to retrieve a single Event Webhook by ID.**
If you do not pass a webhook ID to this endpoint, it will return your oldest webhook by `created_date`. This means the default webhook returned by this endpoint when no ID is provided will be the first one you created. This functionality allows customers who do not have multiple webhooks to use this endpoint to retrieve their only webhook, even if they do not supply an ID. If you have multiple webhooks, you can retrieve their IDs using the [**Get All Event Webhooks**](https://docs.sendgrid.com/api-reference/webhooks/get-all-event-webhooks) endpoint.
### Event settings
Your webhook will be returned with all of its settings, which include the events that will be included in the POST request by the webhook and the URL where they will be sent. If an event type is marked as `true`, the event webhook will send information about that event type. See the [**Event Webhook Reference**](https://docs.sendgrid.com/for-developers/tracking-events/event#delivery-events) 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.'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/Include'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EventWebhookNoDatesResponse'
examples:
One of Multiple Webhooks:
value:
enabled: true
url: https://emaildelivery.example.com
group_resubscribe: false
delivered: true
group_unsubscribe: false
spam_report: true
bounce: true
deferred: true
unsubscribe: true
processed: true
open: true
click: true
dropped: true
friendly_name: Delivery Webhook
id: 77d4a5da-7015-11ed-a1eb-0242ac120002
oauth_client_id: a835e7210bbb47edbfa71bdfc909b2d7
oauth_token_url: https://oauthservice.example.com
public_key: 123publickeyabc
created_at: '2023-01-01T12:00:00Z'
updated_at: '2023-02-15T10:00:00Z'
One of One Webhooks:
value:
enabled: true
url: https://emaildelivery.example.com
group_resubscribe: false
delivered: true
group_unsubscribe: false
spam_report: true
bounce: true
deferred: true
unsubscribe: true
processed: true
open: true
click: true
dropped: true
id: 77d4a5da-7015-11ed-a1eb-0242ac120002
oauth_client_id: a835e7210bbb47edbfa71bdfc909b2d7
oauth_token_url: https://oauthservice.example.com
public_key: 123publickeyabc
'404':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
description: Error message.
examples:
Not found:
value:
errors:
- message: Invalid id provided.
patch:
operationId: UpdateEventWebhook
summary: Update a single Event Webhook by ID.
tags:
- Event Webhook
description: '**This endpoint allows you to update a single Event Webhook by ID.**
If you do not pass a webhook ID to this endpoint, it will update and return your oldest webhook by `created_date`. This means the default webhook updated by this endpoint when no ID is provided will be the first one you created. This functionality allows customers who do not have multiple webhooks to use this endpoint to update their only webhook, even if they do not supply an ID. If you have multiple webhooks, you can retrieve their IDs using the [**Get All Event Webhooks**](https://docs.sendgrid.com/api-reference/webhooks/get-all-event-webhooks) endpoint.
### Enable or disable the webhook
You can set the `enabled` property to `true` to enable the webhook or `false` to disable it. Disabling a webhook will not delete it from your account, but it will prevent the webhook from sending events to your designated URL.
### URL
A webhook''s URL is the endpoint where you want the webhook to send POST requests containing event data. No more than one webhook may be configured to send to the same URL. SendGrid will return an error if you attempt to set a URL for a webhook that is already in use by the user on another webhook.
### Event settings
If an event type is marked as `true`, the event webhook will send information about that event type. See the [**Event Webhook Reference**](https://docs.sendgrid.com/for-developers/tracking-events/event#delivery-events) for details about each event type.
### Webhook identifiers
You may 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.
### OAuth
You can configure OAuth for your webhook by passing the required values to this endpoint in the `oauth_client_id`, `oauth_client_secret`, and `oauth_token_url` properties. To disable OAuth, pass an empty string to this endpoint for each of the OAuth properties. You may share one OAuth configuration across all your webhooks or create unique credentials for each. See our [webhook security documentation](https://docs.sendgrid.com/for-developers/tracking-events/getting-started-event-webhook-security-features#oauth-20) for more detailed information about OAuth and the Event Webhook.
### Signature verification
Enabling signature verification for your webhook is a separate process and cannot be done with this endpoint. You can use the webhook ID to [enable or disable signature verification with the endpoint dedicated for that operation](https://docs.sendgrid.com/api-reference/webhooks/toggle-signature-verification-for-an-event-webhook).'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/Include'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EventWebhookRequest'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EventWebhookUnsignedResponse'
examples:
response:
value:
enabled: true
url: https://emaildelivery.example.com
group_resubscribe: false
delivered: true
group_unsubscribe: false
spam_report: true
bounce: true
deferred: true
unsubscribe: true
processed: true
open: true
click: true
dropped: true
friendly_name: Delivery Webhook
id: 77d4a5da-7015-11ed-a1eb-0242ac120002
oauth_client_id: a835e7210bbb47edbfa71bdfc909b2d7
oauth_token_url: https://oauthservice.example.com
created_date: '2023-01-01T12:00:00Z'
updated_date: '2023-02-15T10:00:00Z'
'400':
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:
Account Change:
value:
errors:
- message: This webhook cannot be modified based on your current billing plan.
Exists:
value:
errors:
- id: 123abc456def890ghi
message: Webhook at 'https://example.com' already exists. Please provide a unique URL.
url: https://example.com
'404':
description: Not found
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
description: Error message.
examples:
Invalid ID:
value:
errors:
- message: Invalid id provided.
delete:
operationId: DeleteEventWebhook
summary: Delete a single Event Webhook by ID.
tags:
- Event Webhook
description: '**This endpoint allows you to delete a single Event Webhook by ID.**
Unlike the [**Get an Event Webhook**](https://docs.sendgri
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/sendgrid-event-webhook-api-openapi.yml