# Webhooks Webhooks allow us to push raw events we collect about your emails over to your servers. Batches of events are delivered through a POST request to the defined target URL. You can use this endpoint to create and manage webhooks, or you can create one from the app. #### Batch Information * Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded. * Each webhook batch contains the header `X-MessageSystems-Batch-ID`, which is useful for detecting and prevention of processing duplicate batches. Additionally within each event the `event_id` is unique and can also be used in duplicate detection and prevention. * Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database. * Webhook batch status is available for 24 hours via the UI or the API. * See [Best Practices for Managing Webhook Data Streams](https://www.sparkpost.com/docs/tech-resources/webhook-data-streams/) for more information on how best to consume webhooks. * See [Webhook Authentication and Security](https://www.sparkpost.com/docs/tech-resources/webhook-authentication/) for highly recommended security measures. #### Event Types You can receive any of the following types of events in webhook payloads: * Message Status Events: * `injection`: Message was accepted for delivery * `delivery`: Message was successfully delivered * `delay`: Message delivery was delayed * `bounce`: Message delivery failed * `spam_complaint`: Recipient marked message as spam * `out_of_band`: Message bounced after initial acceptance * `policy_rejection`: Message was rejected by policy * `generation_failure`: Message generation failed * `generation_rejection`: Message was rejected during generation * Recipient Engagement Events: * `open`: Message was opened * `initial_open`: First time message was opened * `click`: Link in message was clicked * `initial_click`: First time a link was clicked * `amp_click`: Link in AMP version was clicked * `amp_open`: AMP version was opened ### Regional Endpoints Please use the appropriate API endpoint based on your workspace region: * EU workspaces: * US workspaces: ## List all Webhooks > Returns a list of all your webhooks. ```json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhooks allow us to push raw events we collect about your emails over to your servers. Batches of events are delivered through a POST request to the defined target URL. You can use this endpoint to create and manage webhooks, or you can create one from the app.\n\n### Batch Information\n\n* Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded.\n* Each webhook batch contains the header `X-MessageSystems-Batch-ID`, which is useful for detecting and prevention of processing duplicate batches. Additionally within each event the `event_id` is unique and can also be used in duplicate detection and prevention.\n* Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database.\n* Webhook batch status is available for 24 hours via the UI or the API.\n* See [Best Practices for Managing Webhook Data Streams](https://www.sparkpost.com/docs/tech-resources/webhook-data-streams/) for more information on how best to consume webhooks.\n* See [Webhook Authentication and Security](https://www.sparkpost.com/docs/tech-resources/webhook-authentication/) for highly recommended security measures.\n\n### Event Types\n\nYou can receive any of the following types of events in webhook payloads:\n\n* Message Status Events:\n - `injection`: Message was accepted for delivery\n - `delivery`: Message was successfully delivered\n - `delay`: Message delivery was delayed\n - `bounce`: Message delivery failed\n - `spam_complaint`: Recipient marked message as spam\n - `out_of_band`: Message bounced after initial acceptance\n - `policy_rejection`: Message was rejected by policy\n - `generation_failure`: Message generation failed\n - `generation_rejection`: Message was rejected during generation\n\n* Recipient Engagement Events:\n - `open`: Message was opened\n - `initial_open`: First time message was opened\n - `click`: Link in message was clicked\n - `initial_click`: First time a link was clicked\n - `amp_click`: Link in AMP version was clicked\n - `amp_open`: AMP version was opened\n\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/webhooks":{"get":{"tags":["Webhooks"],"summary":"List all Webhooks","description":"Returns a list of all your webhooks.","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successfully retrieved webhooks list","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"target":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"auth_type":{"type":"string"},"auth_request_details":{"type":"object"},"auth_credentials":{"type":"object"},"last_successful":{"type":"string","format":"date-time"},"last_failure":{"type":"string","format":"date-time"},"active":{"type":"boolean"},"links":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"rel":{"type":"string"},"method":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}}}}}} ``` ## Create a Webhook > Create a new webhook. When a webhook is created, a test POST request is sent to the target URL.\ > If this request does not receive an HTTP 200 response, your request will fail with HTTP 400 and the webhook will not be created.\ > If created successfully, the webhook will begin to receive event data after 1 minute.
```json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhooks allow us to push raw events we collect about your emails over to your servers. Batches of events are delivered through a POST request to the defined target URL. You can use this endpoint to create and manage webhooks, or you can create one from the app.\n\n### Batch Information\n\n* Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded.\n* Each webhook batch contains the header `X-MessageSystems-Batch-ID`, which is useful for detecting and prevention of processing duplicate batches. Additionally within each event the `event_id` is unique and can also be used in duplicate detection and prevention.\n* Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database.\n* Webhook batch status is available for 24 hours via the UI or the API.\n* See [Best Practices for Managing Webhook Data Streams](https://www.sparkpost.com/docs/tech-resources/webhook-data-streams/) for more information on how best to consume webhooks.\n* See [Webhook Authentication and Security](https://www.sparkpost.com/docs/tech-resources/webhook-authentication/) for highly recommended security measures.\n\n### Event Types\n\nYou can receive any of the following types of events in webhook payloads:\n\n* Message Status Events:\n - `injection`: Message was accepted for delivery\n - `delivery`: Message was successfully delivered\n - `delay`: Message delivery was delayed\n - `bounce`: Message delivery failed\n - `spam_complaint`: Recipient marked message as spam\n - `out_of_band`: Message bounced after initial acceptance\n - `policy_rejection`: Message was rejected by policy\n - `generation_failure`: Message generation failed\n - `generation_rejection`: Message was rejected during generation\n\n* Recipient Engagement Events:\n - `open`: Message was opened\n - `initial_open`: First time message was opened\n - `click`: Link in message was clicked\n - `initial_click`: First time a link was clicked\n - `amp_click`: Link in AMP version was clicked\n - `amp_open`: AMP version was opened\n\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/webhooks":{"post":{"tags":["Webhooks"],"summary":"Create a Webhook","description":"Create a new webhook. When a webhook is created, a test POST request is sent to the target URL.\nIf this request does not receive an HTTP 200 response, your request will fail with HTTP 400 and the webhook will not be created.\nIf created successfully, the webhook will begin to receive event data after 1 minute.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","target","events"],"properties":{"name":{"type":"string","description":"Name for webhook"},"target":{"type":"string","description":"URL of the target to which to POST event batches"},"events":{"type":"array","description":"Array of event types this webhook will send","items":{"type":"string"}},"active":{"type":"boolean","description":"The status of the webhook","default":true},"custom_headers":{"type":"object","description":"Object of custom headers to be used during POST requests to target"},"auth_type":{"type":"string","enum":["none","basic","oauth2"],"default":"none","description":"Type of authentication to be used during POST requests to target"},"auth_request_details":{"type":"object","description":"Object containing details needed for OAuth 2.0 authentication","properties":{"url":{"type":"string","description":"The URL for the authorization server"},"body":{"type":"object","description":"The body to send in the request to the authorization server"}}},"auth_credentials":{"type":"object","description":"Object containing credentials for Basic Authentication","properties":{"username":{"type":"string","description":"The username for Basic Authentication"},"password":{"type":"string","description":"The password for Basic Authentication"}}}}}}}},"responses":{"200":{"description":"Webhook created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"links":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"rel":{"type":"string"},"method":{"type":"array","items":{"type":"string"}}}}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` ## Retrieve a Webhook > Retrieve a specific webhook by ID. ```json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhooks allow us to push raw events we collect about your emails over to your servers. Batches of events are delivered through a POST request to the defined target URL. You can use this endpoint to create and manage webhooks, or you can create one from the app.\n\n### Batch Information\n\n* Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded.\n* Each webhook batch contains the header `X-MessageSystems-Batch-ID`, which is useful for detecting and prevention of processing duplicate batches. Additionally within each event the `event_id` is unique and can also be used in duplicate detection and prevention.\n* Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database.\n* Webhook batch status is available for 24 hours via the UI or the API.\n* See [Best Practices for Managing Webhook Data Streams](https://www.sparkpost.com/docs/tech-resources/webhook-data-streams/) for more information on how best to consume webhooks.\n* See [Webhook Authentication and Security](https://www.sparkpost.com/docs/tech-resources/webhook-authentication/) for highly recommended security measures.\n\n### Event Types\n\nYou can receive any of the following types of events in webhook payloads:\n\n* Message Status Events:\n - `injection`: Message was accepted for delivery\n - `delivery`: Message was successfully delivered\n - `delay`: Message delivery was delayed\n - `bounce`: Message delivery failed\n - `spam_complaint`: Recipient marked message as spam\n - `out_of_band`: Message bounced after initial acceptance\n - `policy_rejection`: Message was rejected by policy\n - `generation_failure`: Message generation failed\n - `generation_rejection`: Message was rejected during generation\n\n* Recipient Engagement Events:\n - `open`: Message was opened\n - `initial_open`: First time message was opened\n - `click`: Link in message was clicked\n - `initial_click`: First time a link was clicked\n - `amp_click`: Link in AMP version was clicked\n - `amp_open`: AMP version was opened\n\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/webhooks/{webhookId}":{"get":{"tags":["Webhooks"],"summary":"Retrieve a Webhook","description":"Retrieve a specific webhook by ID.","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhookId","in":"path","description":"The ID of the webhook","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successfully retrieved webhook","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"name":{"type":"string"},"target":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"auth_type":{"type":"string"},"auth_request_details":{"type":"object"},"auth_credentials":{"type":"object"},"active":{"type":"boolean"},"links":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"rel":{"type":"string"},"method":{"type":"array","items":{"type":"string"}}}}}}}}}}}}}}}}} ``` ## Update a Webhook > Update an existing webhook. If you change the target URL, a test POST request will be sent.\ > If this request does not receive an HTTP 200 response, your request will fail with HTTP 400.
```json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhooks allow us to push raw events we collect about your emails over to your servers. Batches of events are delivered through a POST request to the defined target URL. You can use this endpoint to create and manage webhooks, or you can create one from the app.\n\n### Batch Information\n\n* Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded.\n* Each webhook batch contains the header `X-MessageSystems-Batch-ID`, which is useful for detecting and prevention of processing duplicate batches. Additionally within each event the `event_id` is unique and can also be used in duplicate detection and prevention.\n* Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database.\n* Webhook batch status is available for 24 hours via the UI or the API.\n* See [Best Practices for Managing Webhook Data Streams](https://www.sparkpost.com/docs/tech-resources/webhook-data-streams/) for more information on how best to consume webhooks.\n* See [Webhook Authentication and Security](https://www.sparkpost.com/docs/tech-resources/webhook-authentication/) for highly recommended security measures.\n\n### Event Types\n\nYou can receive any of the following types of events in webhook payloads:\n\n* Message Status Events:\n - `injection`: Message was accepted for delivery\n - `delivery`: Message was successfully delivered\n - `delay`: Message delivery was delayed\n - `bounce`: Message delivery failed\n - `spam_complaint`: Recipient marked message as spam\n - `out_of_band`: Message bounced after initial acceptance\n - `policy_rejection`: Message was rejected by policy\n - `generation_failure`: Message generation failed\n - `generation_rejection`: Message was rejected during generation\n\n* Recipient Engagement Events:\n - `open`: Message was opened\n - `initial_open`: First time message was opened\n - `click`: Link in message was clicked\n - `initial_click`: First time a link was clicked\n - `amp_click`: Link in AMP version was clicked\n - `amp_open`: AMP version was opened\n\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/webhooks/{webhookId}":{"put":{"tags":["Webhooks"],"summary":"Update a Webhook","description":"Update an existing webhook. If you change the target URL, a test POST request will be sent.\nIf this request does not receive an HTTP 200 response, your request will fail with HTTP 400.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhookId","in":"path","description":"The ID of the webhook","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for webhook"},"target":{"type":"string","description":"URL of the target to which to POST event batches"},"events":{"type":"array","description":"Array of event types this webhook will send","items":{"type":"string"}},"active":{"type":"boolean","description":"The status of the webhook"},"custom_headers":{"type":"object","description":"Object of custom headers to be used during POST requests to target"},"auth_type":{"type":"string","enum":["none","basic","oauth2"],"description":"Type of authentication to be used during POST requests to target"},"auth_request_details":{"type":"object","description":"Object containing details needed for OAuth 2.0 authentication"},"auth_credentials":{"type":"object","description":"Object containing credentials for Basic Authentication"}}}}}},"responses":{"200":{"description":"Webhook updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"links":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"rel":{"type":"string"},"method":{"type":"array","items":{"type":"string"}}}}}}}}}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` ## Delete a Webhook > Delete a specific webhook by ID. ```json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhooks allow us to push raw events we collect about your emails over to your servers. Batches of events are delivered through a POST request to the defined target URL. You can use this endpoint to create and manage webhooks, or you can create one from the app.\n\n### Batch Information\n\n* Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded.\n* Each webhook batch contains the header `X-MessageSystems-Batch-ID`, which is useful for detecting and prevention of processing duplicate batches. Additionally within each event the `event_id` is unique and can also be used in duplicate detection and prevention.\n* Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database.\n* Webhook batch status is available for 24 hours via the UI or the API.\n* See [Best Practices for Managing Webhook Data Streams](https://www.sparkpost.com/docs/tech-resources/webhook-data-streams/) for more information on how best to consume webhooks.\n* See [Webhook Authentication and Security](https://www.sparkpost.com/docs/tech-resources/webhook-authentication/) for highly recommended security measures.\n\n### Event Types\n\nYou can receive any of the following types of events in webhook payloads:\n\n* Message Status Events:\n - `injection`: Message was accepted for delivery\n - `delivery`: Message was successfully delivered\n - `delay`: Message delivery was delayed\n - `bounce`: Message delivery failed\n - `spam_complaint`: Recipient marked message as spam\n - `out_of_band`: Message bounced after initial acceptance\n - `policy_rejection`: Message was rejected by policy\n - `generation_failure`: Message generation failed\n - `generation_rejection`: Message was rejected during generation\n\n* Recipient Engagement Events:\n - `open`: Message was opened\n - `initial_open`: First time message was opened\n - `click`: Link in message was clicked\n - `initial_click`: First time a link was clicked\n - `amp_click`: Link in AMP version was clicked\n - `amp_open`: AMP version was opened\n\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/webhooks/{webhookId}":{"delete":{"tags":["Webhooks"],"summary":"Delete a Webhook","description":"Delete a specific webhook by ID.","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhookId","in":"path","description":"The ID of the webhook","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Webhook deleted successfully"}}}}}} ``` ## Validate a Webhook > The validation request sends an example message event batch to the target URL,\ > validates that the target responds with HTTP 200, and returns information on the response received.
```json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhooks allow us to push raw events we collect about your emails over to your servers. Batches of events are delivered through a POST request to the defined target URL. You can use this endpoint to create and manage webhooks, or you can create one from the app.\n\n### Batch Information\n\n* Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded.\n* Each webhook batch contains the header `X-MessageSystems-Batch-ID`, which is useful for detecting and prevention of processing duplicate batches. Additionally within each event the `event_id` is unique and can also be used in duplicate detection and prevention.\n* Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database.\n* Webhook batch status is available for 24 hours via the UI or the API.\n* See [Best Practices for Managing Webhook Data Streams](https://www.sparkpost.com/docs/tech-resources/webhook-data-streams/) for more information on how best to consume webhooks.\n* See [Webhook Authentication and Security](https://www.sparkpost.com/docs/tech-resources/webhook-authentication/) for highly recommended security measures.\n\n### Event Types\n\nYou can receive any of the following types of events in webhook payloads:\n\n* Message Status Events:\n - `injection`: Message was accepted for delivery\n - `delivery`: Message was successfully delivered\n - `delay`: Message delivery was delayed\n - `bounce`: Message delivery failed\n - `spam_complaint`: Recipient marked message as spam\n - `out_of_band`: Message bounced after initial acceptance\n - `policy_rejection`: Message was rejected by policy\n - `generation_failure`: Message generation failed\n - `generation_rejection`: Message was rejected during generation\n\n* Recipient Engagement Events:\n - `open`: Message was opened\n - `initial_open`: First time message was opened\n - `click`: Link in message was clicked\n - `initial_click`: First time a link was clicked\n - `amp_click`: Link in AMP version was clicked\n - `amp_open`: AMP version was opened\n\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/webhooks/{webhookId}/validate":{"post":{"tags":["Webhooks"],"summary":"Validate a Webhook","description":"The validation request sends an example message event batch to the target URL,\nvalidates that the target responds with HTTP 200, and returns information on the response received.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhookId","in":"path","description":"The ID of the webhook","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook validation successful","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"object","properties":{"msg":{"type":"string"},"response":{"type":"object","properties":{"status":{"type":"integer"},"headers":{"type":"object"},"body":{"type":"string"}}}}}}}}}}}}}}} ``` ## Retrieve Batch Status Information > Get status information about webhook batches. Status information is provided for failed batches\ > and those that succeeded on retry. Batch status is available for 24 hours.
```json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Webhooks","description":"Webhooks allow us to push raw events we collect about your emails over to your servers. Batches of events are delivered through a POST request to the defined target URL. You can use this endpoint to create and manage webhooks, or you can create one from the app.\n\n### Batch Information\n\n* Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded.\n* Each webhook batch contains the header `X-MessageSystems-Batch-ID`, which is useful for detecting and prevention of processing duplicate batches. Additionally within each event the `event_id` is unique and can also be used in duplicate detection and prevention.\n* Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database.\n* Webhook batch status is available for 24 hours via the UI or the API.\n* See [Best Practices for Managing Webhook Data Streams](https://www.sparkpost.com/docs/tech-resources/webhook-data-streams/) for more information on how best to consume webhooks.\n* See [Webhook Authentication and Security](https://www.sparkpost.com/docs/tech-resources/webhook-authentication/) for highly recommended security measures.\n\n### Event Types\n\nYou can receive any of the following types of events in webhook payloads:\n\n* Message Status Events:\n - `injection`: Message was accepted for delivery\n - `delivery`: Message was successfully delivered\n - `delay`: Message delivery was delayed\n - `bounce`: Message delivery failed\n - `spam_complaint`: Recipient marked message as spam\n - `out_of_band`: Message bounced after initial acceptance\n - `policy_rejection`: Message was rejected by policy\n - `generation_failure`: Message generation failed\n - `generation_rejection`: Message was rejected during generation\n\n* Recipient Engagement Events:\n - `open`: Message was opened\n - `initial_open`: First time message was opened\n - `click`: Link in message was clicked\n - `initial_click`: First time a link was clicked\n - `amp_click`: Link in AMP version was clicked\n - `amp_open`: AMP version was opened\n\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}}},"paths":{"/workspaces/{workspaceId}/reach/webhooks/{webhookId}/batch-status":{"get":{"tags":["Webhooks"],"summary":"Retrieve Batch Status Information","description":"Get status information about webhook batches. Status information is provided for failed batches\nand those that succeeded on retry. Batch status is available for 24 hours.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"webhookId","in":"path","description":"The ID of the webhook","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of results to return","schema":{"type":"integer","default":1000}}],"responses":{"200":{"description":"Successfully retrieved batch status information","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"batch_id":{"type":"string"},"ts":{"type":"string","format":"date-time"},"attempts":{"type":"integer"},"response_code":{"type":"string"},"failure_code":{"type":"string"},"latency":{"type":"integer"}}}}}}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bird.com/api/email-api/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.