openapi: 3.1.0 security: - BearerAuth: [] info: title: Twilio SendGrid Webhook Configuration API summary: The Twilio SendGrid Webhooks API allows you to configure the Event and Parse Webhooks. description: 'The Twilio SendGrid Webhooks API allows you to configure the Event and Parse Webhooks. Email is a data-rich channel, and implementing the Event Webhook will allow you to consume those data in nearly real time. This means you can actively monitor and participate in the health of your email program throughout the send cycle. The Inbound Parse Webhook processes all incoming email for a domain or subdomain, parses the contents and attachments and then POSTs `multipart/form-data` to a URL that you choose. ' 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: webhooks servers: - url: https://api.sendgrid.com description: for global users and subusers - url: https://api.eu.sendgrid.com description: for EU regional subusers 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.**\n\nRetry\ \ logic for this endpoint differs from other endpoints, which use a rolling\ \ 24-hour retry.\n\nThis 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.\n\n\ ### Test OAuth configuration\n\nTo test your OAuth configuration, you must\ \ include the necessary OAuth properties: `oauth_client_id`, `oauth_client_secret`,\ \ and `oauth_token_url`.\n\nIf the webhook you are testing already has OAuth\ \ credentials saved, you will provide only the `oauth_client_id` and `oauth_token_url`\u2014\ 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.\n\nYou 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.sendgrid.com/api-reference/webhooks/get-an-event-webhook) and [**Update an Event Webhook**](https://docs.sendgrid.com/api-reference/webhooks/update-an-event-webhook) endpoints, which will operate on your oldest webhook by `created_date` when you don''t provide an ID, this endpoint will return an error if you do not pass it an ID. This behavior prevents customers from unintentionally deleting a webhook. You can retrieve your webhooks'' IDs using the [**Get All Event Webhooks**](https://docs.sendgrid.com/api-reference/webhooks/get-all-event-webhooks) endpoint. ### Enable or disable the webhook This endpoint will permanently delete the webhook specified. If you instead want to disable a webhook, you can set the `enabled` property to `false` with the [**Update an Event Webhook**](https://docs.sendgrid.com/api-reference/webhooks/update-an-event-webhook) endpoint.' parameters: - $ref: '#/components/parameters/OnBehalfOf' - $ref: '#/components/parameters/RequestId' responses: '204': description: No Content '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/parse/settings: get: operationId: ListParseSetting summary: Retrieve all parse settings tags: - Parse Webhook description: '**This endpoint allows you to retrieve all of your current inbound parse settings.**' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: type: object properties: result: type: array description: The list of your current inbound parse settings. items: $ref: '#/components/schemas/ParseSetting' examples: response: value: result: - url: http://mydomain.com/parse hostname: mail.mydomain.com spam_check: true send_raw: true '401': $ref: '#/components/responses/Webhook401' '403': $ref: '#/components/responses/Webhook403' '404': $ref: '#/components/responses/Webhook404' '500': $ref: '#/components/responses/Webhook500' post: operationId: CreateParseSetting summary: Create a parse setting tags: - Parse Webhook description: '**This endpoint allows you to create a new inbound parse setting.** Creating an Inbound Parse setting requires two pieces of information: a `url` and a `hostname`. The `hostname` must correspond to a domain authenticated by Twilio SendGrid on your account. If you need to complete domain authentication, you can use the [Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth) or the **Authenticate a Domain** endpoint. See [**How to Set Up Domain Authentication**](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) for instructions. Any email received by the `hostname` will be parsed when you complete this setup. You must also add a Twilio SendGrid MX record to this domain''s DNS records. See [**Setting up the Inbound Parse Webhook**](https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/) for full instructions. The `url` represents a location where the parsed message data will be delivered. Twilio SendGrid will make an HTTP POST request to this `url` with the message data. The `url` must be publicly reachable, and your application must return a `200` status code to signal that the message data has been received.' parameters: - $ref: '#/components/parameters/OnBehalfOf' requestBody: $ref: '#/components/requestBodies/PostPatchParseSetting' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/ParseSetting' examples: response: value: url: http://email.myhostname.com hostname: myhostname.com spam_check: false send_raw: true '401': $ref: '#/components/responses/Webhook401' '403': $ref: '#/components/responses/Webhook403' '404': $ref: '#/components/responses/Webhook404' '500': $ref: '#/components/responses/Webhook500' /v3/user/webhooks/parse/settings/{hostname}: parameters: - name: hostname in: path description: The hostname associated with the inbound parse setting that you would like to retrieve. required: true schema: type: string get: operationId: GetParseSetting summary: Retrieve a specific parse setting tags: - Parse Webhook description: '**This endpoint allows you to retrieve a specific inbound parse setting by hostname.** You can retrieve all your Inbound Parse settings and their associated host names with the "Retrieve all parse settings" endpoint.' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ParseSetting' examples: response: value: url: http://mydomain.com/parse hostname: mail.mydomain.com spam_check: true send_raw: true '401': $ref: '#/components/responses/Webhook401' '403': $ref: '#/components/responses/Webhook403' '404': $ref: '#/components/responses/Webhook404' '500': $ref: '#/components/responses/Webhook500' patch: operationId: UpdateParseSetting summary: Update a parse setting tags: - Parse Webhook description: '**This endpoint allows you to update a specific inbound parse setting by hostname.** You can retrieve all your Inbound Parse settings and their associated host names with the "Retrieve all parse settings" endpoint.' parameters: - $ref: '#/components/parameters/OnBehalfOf' requestBody: $ref: '#/components/requestBodies/PostPatchParseSetting' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ParseSetting' examples: response: value: url: http://mydomain.com/parse hostname: mail.mydomain.com spam_check: true send_raw: true '401': $ref: '#/components/responses/Webhook401' '403': $ref: '#/components/responses/Webhook403' '404': $ref: '#/components/responses/Webhook404' '500': $ref: '#/components/responses/Webhook500' delete: operationId: DeleteParseSetting summary: Delete a parse setting tags: - Parse Webhook description: '**This endpoint allows you to delete a specific inbound parse setting by hostname.** You can retrieve all your Inbound Parse settings and their associated host names with the "Retrieve all parse settings" endpoint.' parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '204': description: '' '401': $ref: '#/components/responses/Webhook401' '403': $ref: '#/components/responses/Webhook403' '404': $ref: '#/components/responses/Webhook404' '500': $ref: '#/components/responses/Webhook500' /v3/user/webhooks/parse/stats: get: operationId: ListParseStatic summary: Retrieves Inbound Parse Webhook statistics. tags: - Parse Webhook description: '**This endpoint allows you to retrieve the statistics for your Parse Webhook usage.** SendGrid''s Inbound Parse Webhook allows you to parse the contents and attachments of incoming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 30MB in size, including all attachments. There are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://docs.sendgrid.com/for-developers/sending-email/libraries#webhook-libraries).' parameters: - name: limit in: query description: The number of statistics to return on each page. required: false schema: type: string - name: offset in: query description: The number of statistics to skip. required: false schema: type: string - name: aggregated_by in: query description: 'How you would like the statistics to by grouped. ' required: false schema: type: string $ref: '#/components/schemas/AggregatedBy' - name: start_date in: query description: The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD required: true schema: type: string - name: end_date in: query description: The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD required: false schema: type: string default: The day the request is made. - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: '' content: application/json: schema: type: array items: type: object properties: date: type: string description: The date that the stats were collected. stats: type: array description: The Parse Webhook usage statistics. items: type: object properties: metrics: type: object properties: received: type: number description: The number of emails received and parsed by the Parse Webhook. required: - received required: - date - stats examples: response: value: - date: '2015-10-11' stats: - metrics: received: 0 - date: '2015-10-12' stats: - metrics: received: 0 - date: '2015-10-13' stats: - metrics: received: 0 - date: '2015-10-14' stats: - metrics: received: 0 - date: '2015-10-15' stats: - metrics: received: 0 - date: '2015-10-16' stats: - metrics: received: 0 - date: '2015-10-17' stats: - metrics: received: 0 - date: '2015-10-18' stats: - metrics: received: 0 - date: '2015-10-19' stats: - metrics: received: 0 - date: '2015-10-20' stats: - metrics: received: 0 - date: '2015-10-21' stats: - metrics: received: 0 - date: '2015-10-22' stats: - metrics: received: 0 - date: '2015-10-23' stats: - metrics: received: 0 - date: '2015-10-24' stats: - metrics: received: 0 - date: '2015-10-25' stats: - metrics: received: 0 - date: '2015-10-26' stats: - metrics: received: 0 - date: '2015-10-27' stats: - metrics: received: 0 - date: '2015-10-28' stats: - metrics: received: 0 - date: '2015-10-29' stats: - metrics: received: 0 - date: '2015-10-30' stats: - metrics: received: 0 - date: '2015-10-31' stats: - metrics: received: 0 - date: '2015-11-01' stats: - metrics: received: 0 - date: '2015-11-02' stats: - metrics: received: 0 - date: '2015-11-03' stats: - metrics: received: 0 - date: '2015-11-04' stats: - metrics: received: 0 - date: '2015-11-05' stats: - metrics: received: 0 - date: '2015-11-06' stats: - metrics: received: 0 - date: '2015-11-07' stats: - metrics: received: 0 - date: '2015-11-08' stats: - metrics: received: 0 - date: '2015-11-09' stats: - metrics: received: 0 - date: '2015-11-10' stats: - metrics: received: 0 /v3/user/webhooks/security/policies: post: operationId: CreateSecurityPolicy summary: Create a new webhook security policy tags: - Webhook Security description: 'Create a new webhook security policy. Note: One of signature or oauth must be given to have a valid security policy. ' parameters: - $ref: '#/components/parameters/OnBehalfOf' requestBody: content: application/json: schema: type: object properties: name: type: string description: User-defined policy name oauth: type: object properties: client_id: type: string client_secret: type: string token_url: type: string scopes: type: array items: type: string signature: type: object properties: enabled: type: boolean responses: '201': description: Created content: application/json: schema: type: object properties: policy: type: object properties: id: type: string name: type: string oauth: type: object properties: client_id: type: string token_url: type: string scopes: type: array items: type: string signature: type: object properties: public_key: type: string get: operationId: ListAllSecurityPolicies summary: Retrieve all webhook security policies for your account tags: - Webhook Security description: Returns a list of all webhook security policies configured for your account, including their IDs, names, and security configurations. parameters: - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: Success content: application/json: schema: type: object properties: policies: type: array items: type: object properties: id: type: string name: type: string oauth: type: object properties: client_id: type: string token_url: type: string scopes: type: array items: type: string signature: type: object properties: public_key: type: string /v3/user/webhooks/security/policies/{id}: patch: operationId: UpdateSecurityPolicy summary: Update an existing webhook security policy tags: - Webhook Security description: Update an existing webhook security policy with new configuration values. parameters: - name: id in: path required: true schema: type: string - $ref: '#/components/parameters/OnBehalfOf' requestBody: content: application/json: schema: type: object properties: name: type: string description: User-defined policy name oauth: type: object properties: client_id: type: string client_secret: type: string token_url: type: string scopes: type: array items: type: string signature: type: object properties: enabled: type: boolean responses: '200': description: Success content: application/json: schema: type: object properties: policy: type: object properties: id: type: string name: type: string oauth: type: object properties: client_id: type: string token_url: type: string scopes: type: array items: type: string get: operationId: GetSecurityPolicy summary: Retrieve a specific webhook security policy tags: - Webhook Security description: Retrieve the details of a specific webhook security policy by its ID. parameters: - name: id in: path required: true schema: type: string - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: Success content: application/json: schema: type: object properties: policy: type: object properties: id: type: string name: type: string oauth: type: object properties: client_id: type: string token_url: type: string scopes: type: array items: type: string signature: type: object properties: public_key: type: string delete: operationId: DeleteSecurityPolicy summary: Delete a specific webhook security policy tags: - Webhook Security description: Permanently delete a webhook security policy by its ID. parameters: - name: id in: path required: true schema: type: string - name: force in: query required: false schema: type: boolean - $ref: '#/components/parameters/OnBehalfOf' responses: '200': description: Success content: application/json: schema: type: object properties: policy: type: string nullable: true components: schemas: EventWebhookRequest: title: Create and Update Event Webhook Request Body type: object 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](https://docs.sendgrid.com/ui/sending-email/create-and-manage-unsubscribe-groups) by updating their subscription preferences. You must [enable Subscription Tracking](https://docs.sendgrid.com/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](https://docs.sendgrid.com/ui/sending-email/create-and-manage-unsubscribe-groups) either by direct link or by updating their subscription preferences. You must [enable Subscription Tracking](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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 required: - url EventWebhookTestRequest: title: Send Event Webhook Test Request type: object properties: id: type: string description: The ID of the Event Webhook you want to retrieve. url: type: string description: The URL where you would like the test notification to be sent. oauth_client_id: type: string description: The client ID Twilio SendGrid sends 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: The `oauth_client_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. 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: The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an 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 required: - url example: id: 77d4a5da-7015-11ed-a1eb-0242ac120002 url: https://emailengagment.example.com oauth_client_id: a835e7210bbb47edbfa71bdfc909b2d7 oauth_client_secret: 335a9b0c65324fd2a62e2953d4b158 oauth_token_url: https://oauthservice.example.com EventWebhookBaseResponseProps: type: object 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](https://docs.sendgrid.com/ui/sending-email/create-and-manage-unsubscribe-groups) by updating their subscription preferences. You must [enable Subscription Tracking](https://docs.sendgrid.com/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](https://docs.sendgrid.com/ui/sending-email/create-and-manage-unsubscribe-groups) either by direct link or by updating their subscription preferences. You must [enable Subscription Tracking](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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. EventWebhookDateResponseProps: type: object properties: 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 EventWebhookOauthResponseProps: type: object properties: 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 EventWebhookSignedResponseProp: type: object properties: public_key: type: string description: The public key you can use to verify the SendGrid signature. EventWebhookUnsignedResponse: type: object 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](https://docs.sendgrid.com/ui/sending-email/create-and-manage-unsubscribe-groups) by updating their subscription preferences. You must [enable Subscription Tracking](https://docs.sendgrid.com/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](https://docs.sendgrid.com/ui/sending-email/create-and-manage-unsubscribe-groups) either by direct link or by updating their subscription preferences. You must [enable Subscription Tracking](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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 EventWebhookSignedResponse: type: object 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](https://docs.sendgrid.com/ui/sending-email/create-and-manage-unsubscribe-groups) by updating their subscription preferences. You must [enable Subscription Tracking](https://docs.sendgrid.com/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](https://docs.sendgrid.com/ui/sending-email/create-and-manage-unsubscribe-groups) either by direct link or by updating their subscription preferences. You must [enable Subscription Tracking](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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 public_key: type: string description: The public key you can use to verify the SendGrid signature. EventWebhookNoDatesResponse: type: object 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](https://docs.sendgrid.com/ui/sending-email/create-and-manage-unsubscribe-groups) by updating their subscription preferences. You must [enable Subscription Tracking](https://docs.sendgrid.com/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](https://docs.sendgrid.com/ui/sending-email/create-and-manage-unsubscribe-groups) either by direct link or by updating their subscription preferences. You must [enable Subscription Tracking](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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](https://docs.sendgrid.com/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. 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 public_key: type: string description: The public key you can use to verify the SendGrid signature. EventWebhookAllResponse: title: 'Event Webhook Response Body: All Webhooks' type: object properties: max_allowed: type: number description: The maximum number of Event Webhooks you can have enabled under your current Twilio SendGrid plan. See the [Twilio SendGrid pricing page](https://sendgrid.com/pricing) for more information about the features available with each plan. webhooks: type: array description: 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. items: $ref: '#/components/schemas/EventWebhookSignedResponse' ParseSetting: title: Parse Setting type: object properties: url: type: string description: The public URL where you would like SendGrid to POST the data parsed from your email. Any emails sent with the given hostname provided (whose MX records have been updated to point to SendGrid) will be parsed and POSTed to this URL. hostname: type: string description: A specific and unique domain or subdomain that you have created to use exclusively to parse your incoming email. For example, `parse.yourdomain.com`. spam_check: type: boolean description: Indicates if you would like SendGrid to check the content parsed from your emails for spam before POSTing them to your domain. send_raw: type: boolean description: Indicates if you would like SendGrid to post the original MIME-type content of your parsed email. When this parameter is set to `true`, SendGrid will send a JSON payload of the content of your email. example: url: http://email.myhostname.com hostname: myhostname.com spam_check: false send_raw: true ErrorResponse: type: object properties: errors: type: array items: type: object properties: message: type: string description: An error message. field: description: When applicable, this property value will be the field that generated the error. nullable: true type: string help: type: object description: When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error. id: type: string description: When applicable, this property value will be an error ID. example: errors: - field: field_name message: error message AggregatedBy: type: string enum: - day - week - month responses: Webhook401: description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Webhook403: description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Webhook404: description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Webhook500: description: '' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string parameters: Include: name: include in: query description: 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](https://docs.sendgrid.com/api-reference/webhooks/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. required: false schema: type: string RequestId: name: id in: path description: The ID of the Event Webhook you want to retrieve. required: true schema: type: string examples: ID Example: value: 77d4a5da-7015-11ed-a1eb-0242ac120002 OnBehalfOf: 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**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.' required: false schema: type: string examples: {} requestBodies: PostPatchParseSetting: content: application/json: schema: $ref: '#/components/schemas/ParseSetting' headers: {} securitySchemes: BearerAuth: type: http scheme: bearer description: Twilio SendGrid requires you to authenticate with its APIs using an API key. The API key must be sent as a bearer token in the Authorization header. tags: - name: Event Webhook description: Twilio SendGrid Event Webhook API - name: Parse Webhook description: Twilio SendGrid Parse Webhook API - name: Webhook Security description: Twilio SendGrid Webhook Security API externalDocs: description: Twilio SendGrid's official developer documentation. url: https://www.twilio.com/docs/sendgrid