URL endpoint to receive webhook POST requests.
Must:
Be an absolute http:// or https:// URL with a host. Anything else is rejected with HTTP 422. Use HTTPS: over plain HTTP, event data travels unencrypted.
Be publicly accessible
Return 2xx status within 10 seconds
Handle duplicate deliveries (use eventId for idempotency)
Fire with the real-time list cleaning result of each email (Validation event, type 82). Needs the Real-Time List Cleaning add-on. Off unless set to true. On update, leaving this out keeps the current value. See Real-Time Validation Results.
Signing secret for this webhook. When set, every request to the webhook carries X-SendPost-Signature, the hex-encoded HMAC-SHA256 of the raw request body keyed with this secret. Without a secret, requests are sent unsigned; your Account API Key is never used for signing. Leading and trailing spaces are removed. On update, leaving this out keeps the current secret and "" removes it. See Webhook Signature Verification.
Narrow which Dropped reasons and Validation results this webhook receives. Leave out dropped or validated and everything in it stays on. Inside either object, list every key: a key you leave out counts as false. On update, this replaces the stored options, so send both objects if you use both. Not returned in webhook responses.
Show child attributes
Response
Webhook created successfully.
Webhook configuration for receiving real-time email event notifications.
When events occur (delivery, open, click, bounce, etc.), SendPost sends
HTTP POST requests to your configured webhook URL.
Trigger webhook when recipient marks email as spam.
The recipient is automatically added to suppression list.
Monitor this closely - high spam rates damage sender reputation.
Trigger webhook with the real-time list cleaning result of each email (Validation event, type 82). Needs the Real-Time List Cleaning add-on. Only present in responses when true. See Real-Time Validation Results.
UNIX epoch timestamp in nanoseconds when the webhook was created
Example:
1704067200000000000
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"SendPost Docs","colors":{"primary":"#5750EC","light":"#5750EC","dark":"#5750EC"},"logo":{"light":"https://mintcdn.com/sendx-43e2b6a9/xWJ6M32vFagLUxJg/logo/sendpost.svg?fit=max\u0026auto=format\u0026n=xWJ6M32vFagLUxJg\u0026q=85\u0026s=fc1d92fba901bca2cbab1ee394bc02ed","dark":"https://mintcdn.com/sendx-43e2b6a9/xWJ6M32vFagLUxJg/logo/sendpost.svg?fit=max\u0026auto=format\u0026n=xWJ6M32vFagLUxJg\u0026q=85\u0026s=fc1d92fba901bca2cbab1ee394bc02ed"},"favicon":"https://mintcdn.com/sendx-43e2b6a9/xWJ6M32vFagLUxJg/favicon.svg?fit=max\u0026auto=format\u0026n=xWJ6M32vFagLUxJg\u0026q=85\u0026s=49e9debc4f6238bdb21ed33aa69238f1","navbar":{"links":[{"href":"mailto:dev@sendpost.io","label":"Support"}],"primary":{"type":"button","label":"SendPost","href":"https://app.sendpost.io/"}},"footer":{"socials":{"github":"https://github.com/sendpost","linkedin":"https://www.linkedin.com/company/sendpost"}},"integrations":{"intercom":{"appId":"APP_ID"}},"styling":{"latex":false},"navigation":{"global":{"anchors":[]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"sendx-43e2b6a9","hasAudioNarration":false,"actualSubdomain":"sendx-43e2b6a9","customDomains":["docs.sendpost.io"],"gitSource":{"type":"github","owner":"sendpost","repo":"sendpost-api-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true},"entitlements":{},"buildId":"6aec41183744ce14d0837e22","clientVersion":"0.0.4094","searchFilterCounts":[{"language":"default","tag":"Welcome","count":68},{"language":"default","tag":"API Reference","count":49},{"language":"default","tag":"Guides","count":39},{"language":"default","tag":"Quickstarts","count":22},{"language":"default","tag":"Webhook","count":10},{"language":"default","tag":"Amazon SES","count":7},{"language":"default","tag":"Custom SMTP","count":7},{"language":"default","tag":"SendGrid","count":7},{"language":"default","tag":"Common Use Cases","count":6},{"language":"default","tag":"IPPools","count":6}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"comment-mode","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/webhook/create-a-new-webhook","slug":"/api-reference/webhook/create-a-new-webhook","pageMetadata":{"openapi":"post /account/webhook","title":"Create Webhook","description":"Create a new webhook to receive real-time notifications for email events. Your endpoint will receive HTTP POST requests with event data as they occur.\n\n**Endpoint Requirements:**\n- Must be a publicly accessible absolute `http://` or `https://` URL (use HTTPS)\n- Should return 2xx status within 30 seconds\n- Handle potential duplicate events (use event ID for deduplication)\n- Implement retry/queue logic for reliability\n\n**Choosing Events:**\n- **Engagement Tracking:** `uniqueOpened`, `uniqueClicked` for metrics\n- **Full History:** `opened`, `clicked` for complete event logs\n- **Delivery Monitoring:** `delivered`, `hardBounced`, `softBounced`\n- **Compliance:** `unsubscribed`, `spam`\n\n**Best Practices:**\n- Only enable events you actually need\n- Store events before processing (async processing)\n- Implement idempotency using event IDs\n- Set up monitoring for webhook failures\n\n**Webhook Payload Example:**\n```json\n{\n \"eventId\": \"evt_123\",\n \"event\": \"delivered\",\n \"messageId\": \"msg_456\",\n \"recipient\": \"user@example.com\",\n \"timestamp\": \"2024-01-15T10:30:00Z\"\n}\n```\n","href":"/api-reference/webhook/create-a-new-webhook"},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n span: \"span\",\n strong: \"strong\",\n ul: \"ul\",\n ..._provideComponents(),\n ...props.components\n }, {CodeBlock} = _components;\n if (!CodeBlock) _missingMdxReference(\"CodeBlock\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Create a new webhook to receive real-time notifications for email events. Your endpoint will receive HTTP POST requests with event data as they occur.\"\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"Endpoint Requirements:\"\n })\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Must be a publicly accessible absolute \", _jsx(_components.code, {\n children: \"http://\"\n }), \" or \", _jsx(_components.code, {\n children: \"https://\"\n }), \" URL (use HTTPS)\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Should return 2xx status within 30 seconds\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Handle potential duplicate events (use event ID for deduplication)\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Implement retry/queue logic for reliability\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"Choosing Events:\"\n })\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Engagement Tracking:\"\n }), \" \", _jsx(_components.code, {\n children: \"uniqueOpened\"\n }), \", \", _jsx(_components.code, {\n children: \"uniqueClicked\"\n }), \" for metrics\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Full History:\"\n }), \" \", _jsx(_components.code, {\n children: \"opened\"\n }), \", \", _jsx(_components.code, {\n children: \"clicked\"\n }), \" for complete event logs\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Delivery Monitoring:\"\n }), \" \", _jsx(_components.code, {\n children: \"delivered\"\n }), \", \", _jsx(_components.code, {\n children: \"hardBounced\"\n }), \", \", _jsx(_components.code, {\n children: \"softBounced\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"Compliance:\"\n }), \" \", _jsx(_components.code, {\n children: \"unsubscribed\"\n }), \", \", _jsx(_components.code, {\n children: \"spam\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"Best Practices:\"\n })\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"Only enable events you actually need\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Store events before processing (async processing)\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Implement idempotency using event IDs\"\n }), \"\\n\", _jsx(_components.li, {\n children: \"Set up monitoring for webhook failures\"\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: _jsx(_components.strong, {\n children: \"Webhook Payload Example:\"\n })\n }), \"\\n\", _jsx(CodeBlock, {\n numberOfLines: \"7\",\n language: \"json\",\n children: _jsx(_components.pre, {\n className: \"shiki shiki-themes github-light-default dark-plus\",\n style: {\n backgroundColor: \"#ffffff\",\n \"--shiki-dark-bg\": \"#0B0C0E\",\n color: \"#1f2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n language: \"json\",\n children: _jsxs(_components.code, {\n language: \"json\",\n numberOfLines: \"7\",\n children: [_jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \"{\"\n })\n }), \"\\n\", _jsxs(_components.span, {\n className: \"line\",\n children: [_jsx(_components.span, {\n style: {\n color: \"#116329\",\n \"--shiki-dark\": \"#9CDCFE\"\n },\n children: \" \\\"eventId\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \": \"\n }), _jsx(_components.span, {\n style: {\n color: \"#0A3069\",\n \"--shiki-dark\": \"#CE9178\"\n },\n children: \"\\\"evt_123\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \",\"\n })]\n }), \"\\n\", _jsxs(_components.span, {\n className: \"line\",\n children: [_jsx(_components.span, {\n style: {\n color: \"#116329\",\n \"--shiki-dark\": \"#9CDCFE\"\n },\n children: \" \\\"event\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \": \"\n }), _jsx(_components.span, {\n style: {\n color: \"#0A3069\",\n \"--shiki-dark\": \"#CE9178\"\n },\n children: \"\\\"delivered\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \",\"\n })]\n }), \"\\n\", _jsxs(_components.span, {\n className: \"line\",\n children: [_jsx(_components.span, {\n style: {\n color: \"#116329\",\n \"--shiki-dark\": \"#9CDCFE\"\n },\n children: \" \\\"messageId\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \": \"\n }), _jsx(_components.span, {\n style: {\n color: \"#0A3069\",\n \"--shiki-dark\": \"#CE9178\"\n },\n children: \"\\\"msg_456\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \",\"\n })]\n }), \"\\n\", _jsxs(_components.span, {\n className: \"line\",\n children: [_jsx(_components.span, {\n style: {\n color: \"#116329\",\n \"--shiki-dark\": \"#9CDCFE\"\n },\n children: \" \\\"recipient\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \": \"\n }), _jsx(_components.span, {\n style: {\n color: \"#0A3069\",\n \"--shiki-dark\": \"#CE9178\"\n },\n children: \"\\\"user@example.com\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \",\"\n })]\n }), \"\\n\", _jsxs(_components.span, {\n className: \"line\",\n children: [_jsx(_components.span, {\n style: {\n color: \"#116329\",\n \"--shiki-dark\": \"#9CDCFE\"\n },\n children: \" \\\"timestamp\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \": \"\n }), _jsx(_components.span, {\n style: {\n color: \"#0A3069\",\n \"--shiki-dark\": \"#CE9178\"\n },\n children: \"\\\"2024-01-15T10:30:00Z\\\"\"\n })]\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \"}\"\n })\n }), \"\\n\"]\n })\n })\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"openapi":"post /account/webhook","title":"Create Webhook","description":"Create a new webhook to receive real-time notifications for email events. Your endpoint will receive HTTP POST requests with event data as they occur.\n\n**Endpoint Requirements:**\n- Must be a publicly accessible absolute `http://` or `https://` URL (use HTTPS)\n- Should return 2xx status within 30 seconds\n- Handle potential duplicate events (use event ID for deduplication)\n- Implement retry/queue logic for reliability\n\n**Choosing Events:**\n- **Engagement Tracking:** `uniqueOpened`, `uniqueClicked` for metrics\n- **Full History:** `opened`, `clicked` for complete event logs\n- **Delivery Monitoring:** `delivered`, `hardBounced`, `softBounced`\n- **Compliance:** `unsubscribed`, `spam`\n\n**Best Practices:**\n- Only enable events you actually need\n- Store events before processing (async processing)\n- Implement idempotency using event IDs\n- Set up monitoring for webhook failures\n\n**Webhook Payload Example:**\n```json\n{\n \"eventId\": \"evt_123\",\n \"event\": \"delivered\",\n \"messageId\": \"msg_456\",\n \"recipient\": \"user@example.com\",\n \"timestamp\": \"2024-01-15T10:30:00Z\"\n}\n```\n","href":"/api-reference/webhook/create-a-new-webhook"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"summary":"Create Webhook","description":"Create a new webhook to receive real-time notifications for email events. Your endpoint will receive HTTP POST requests with event data as they occur.\n\n**Endpoint Requirements:**\n- Must be a publicly accessible absolute `http://` or `https://` URL (use HTTPS)\n- Should return 2xx status within 30 seconds\n- Handle potential duplicate events (use event ID for deduplication)\n- Implement retry/queue logic for reliability\n\n**Choosing Events:**\n- **Engagement Tracking:** `uniqueOpened`, `uniqueClicked` for metrics\n- **Full History:** `opened`, `clicked` for complete event logs\n- **Delivery Monitoring:** `delivered`, `hardBounced`, `softBounced`\n- **Compliance:** `unsubscribed`, `spam`\n\n**Best Practices:**\n- Only enable events you actually need\n- Store events before processing (async processing)\n- Implement idempotency using event IDs\n- Set up monitoring for webhook failures\n\n**Webhook Payload Example:**\n```json\n{\n \"eventId\": \"evt_123\",\n \"event\": \"delivered\",\n \"messageId\": \"msg_456\",\n \"recipient\": \"user@example.com\",\n \"timestamp\": \"2024-01-15T10:30:00Z\"\n}\n```\n","operationId":"createWebhook","tags":["Webhook"],"security":["48ee9cf2-702c-4c6a-9911-b8595eca14b2"],"requestBody":"5442a0f9-877b-430d-b317-fd23c426d633","responses":{"201":"793f63aa-13bb-4506-acb9-2ef945db8be6","401":"850dcabb-ab89-4bf2-9fc5-ae8d21d0c61b","403":"5045fd89-577e-432d-9fee-bfcf22ee5255","406":"e4460167-ff7a-4b5f-832e-47a1fab6a74c","422":"dfa819e6-b77e-4b7e-a7cc-dd9f1c99a47a"},"method":"post","type":"path","servers":["3e2bf5d9-3b9c-4724-ba94-ee3efb46f2dc"],"path":"/account/webhook","baseUrlOptions":["https://api.sendpost.io/api/v1"],"title":"Create Webhook","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Request body for creating a new webhook endpoint.\n\n**Event Selection Tips:**\n- For basic tracking: Enable `delivered`, `opened`, `clicked`\n- For suppression sync: Enable `hardBounced`, `unsubscribed`, `spam`\n- For debugging: Enable `dropped`, `softBounced`\n- Use `uniqueOpen`/`uniqueClick` instead of `opened`/`clicked` to reduce volume\n","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"URL endpoint to receive webhook POST requests.\nMust:\n- Be an absolute `http://` or `https://` URL with a host. Anything else is rejected with HTTP 422. Use HTTPS: over plain HTTP, event data travels unencrypted.\n- Be publicly accessible\n- Return 2xx status within 10 seconds\n- Handle duplicate deliveries (use eventId for idempotency)\n","example":"https://app.hooli.com/api/webhooks/sendpost","isRequired":true,"uniqueKey":"url","typeLabel":"string\u003curi>"},"enabled":{"type":"boolean","description":"Whether the webhook is active immediately after creation.\nSet to false to configure and test before activating.\n","default":true,"example":true,"uniqueKey":"enabled","typeLabel":"boolean"},"processed":{"type":"boolean","description":"Fire when email is accepted by SendPost API","default":false,"example":false,"uniqueKey":"processed","typeLabel":"boolean"},"sent":{"type":"boolean","description":"Fire when email is sent to recipient's mail server","default":false,"example":false,"uniqueKey":"sent","typeLabel":"boolean"},"delivered":{"type":"boolean","description":"Fire when email is accepted by recipient's mail server","default":true,"example":true,"uniqueKey":"delivered","typeLabel":"boolean"},"dropped":{"type":"boolean","description":"Fire when email is not sent (suppression, invalid, etc.)","default":true,"example":true,"uniqueKey":"dropped","typeLabel":"boolean"},"smtpDropped":{"type":"boolean","description":"Fire when email is rejected at SMTP level","default":false,"example":false,"uniqueKey":"smtpDropped","typeLabel":"boolean"},"softBounced":{"type":"boolean","description":"Fire on temporary delivery failure (will retry)","default":true,"example":true,"uniqueKey":"softBounced","typeLabel":"boolean"},"hardBounced":{"type":"boolean","description":"Fire on permanent delivery failure","default":true,"example":true,"uniqueKey":"hardBounced","typeLabel":"boolean"},"opened":{"type":"boolean","description":"Fire when email is opened. Fires on EVERY open.\nConsider using `uniqueOpen` instead to reduce volume.\n","default":true,"example":true,"uniqueKey":"opened","typeLabel":"boolean"},"clicked":{"type":"boolean","description":"Fire when a link is clicked. Fires on EVERY click.\nConsider using `uniqueClick` instead to reduce volume.\n","default":true,"example":true,"uniqueKey":"clicked","typeLabel":"boolean"},"unsubscribed":{"type":"boolean","description":"Fire when recipient clicks unsubscribe link","default":true,"example":true,"uniqueKey":"unsubscribed","typeLabel":"boolean"},"spam":{"type":"boolean","description":"Fire when recipient marks email as spam","default":true,"example":true,"uniqueKey":"spam","typeLabel":"boolean"},"uniqueOpen":{"type":"boolean","description":"Fire only on FIRST open of each email (unique opens).\nMore efficient than `opened` if you only need engagement metrics.\n","default":false,"example":false,"uniqueKey":"uniqueOpen","typeLabel":"boolean"},"uniqueClick":{"type":"boolean","description":"Fire only on FIRST click of each email (unique clicks).\nMore efficient than `clicked` if you only need engagement metrics.\n","default":false,"example":false,"uniqueKey":"uniqueClick","typeLabel":"boolean"},"validated":{"type":"boolean","description":"Fire with the real-time list cleaning result of each email (Validation event, type 82). Needs the Real-Time List Cleaning add-on. Off unless set to true. On update, leaving this out keeps the current value. See [Real-Time Validation Results](/api-reference/webhook/validation-results).\n","example":false,"uniqueKey":"validated","typeLabel":"boolean"},"secret":{"type":"string","description":"Signing secret for this webhook. When set, every request to the webhook carries `X-SendPost-Signature`, the hex-encoded HMAC-SHA256 of the raw request body keyed with this secret. Without a secret, requests are sent unsigned; your Account API Key is never used for signing. Leading and trailing spaces are removed. On update, leaving this out keeps the current secret and `\"\"` removes it. See [Webhook Signature Verification](/api-reference/webhook/webhook-signature-verification).\n","example":"8f14e45fceea167a5a36dedd4bea2543","uniqueKey":"secret","typeLabel":"string"},"eventSubOptions":{"type":"object","description":"Narrow which Dropped reasons and Validation results this webhook receives. Leave out `dropped` or `validated` and everything in it stays on. Inside either object, list every key: a key you leave out counts as `false`. On update, this replaces the stored options, so send both objects if you use both. Not returned in webhook responses.\n","properties":{"dropped":{"type":"object","description":"Dropped (type 1) events by reason. Set a reason to `false` to stop receiving it.","properties":{"suppression":{"type":"boolean","description":"The address is on your suppression list.","uniqueKey":"eventSubOptions.dropped.suppression","typeLabel":"boolean"},"systemSuppression":{"type":"boolean","description":"The address already hard-bounced on SendPost.","uniqueKey":"eventSubOptions.dropped.systemSuppression","typeLabel":"boolean"},"blacklist":{"type":"boolean","description":"The address is on SendPost's blocklist.","uniqueKey":"eventSubOptions.dropped.blacklist","typeLabel":"boolean"},"typoDomain":{"type":"boolean","description":"The domain is a known typo domain.","uniqueKey":"eventSubOptions.dropped.typoDomain","typeLabel":"boolean"},"ipPoolCapacity":{"type":"boolean","description":"The IP pool's sending capacity was exceeded.","uniqueKey":"eventSubOptions.dropped.ipPoolCapacity","typeLabel":"boolean"},"subAccountBlocked":{"type":"boolean","description":"The sub-account or the sender domain is blocked.","uniqueKey":"eventSubOptions.dropped.subAccountBlocked","typeLabel":"boolean"},"internalError":{"type":"boolean","description":"Any other reason.","uniqueKey":"eventSubOptions.dropped.internalError","typeLabel":"boolean"}},"uniqueKey":"eventSubOptions.dropped","typeLabel":"object"},"validated":{"type":"object","description":"Validation (type 82) events by result. Set a result to `false` to stop receiving it.","properties":{"valid":{"type":"boolean","uniqueKey":"eventSubOptions.validated.valid","typeLabel":"boolean"},"invalid":{"type":"boolean","uniqueKey":"eventSubOptions.validated.invalid","typeLabel":"boolean"},"catchAll":{"type":"boolean","description":"Results with `validationStatus` \"catch all\".","uniqueKey":"eventSubOptions.validated.catchAll","typeLabel":"boolean"},"unknown":{"type":"boolean","uniqueKey":"eventSubOptions.validated.unknown","typeLabel":"boolean"}},"uniqueKey":"eventSubOptions.validated","typeLabel":"object"}},"uniqueKey":"eventSubOptions","typeLabel":"object"}},"example":{"enabled":true,"url":"https://app.hooli.com/api/webhooks/sendpost","delivered":true,"dropped":true,"hardBounced":true,"softBounced":true,"opened":true,"clicked":true,"unsubscribed":true,"spam":true},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"enabled":true,"url":"https://app.hooli.com/api/webhooks/sendpost","delivered":true,"dropped":true,"hardBounced":true,"softBounced":true,"opened":true,"clicked":true,"unsubscribed":true,"spam":true}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"793f63aa-13bb-4506-acb9-2ef945db8be6":{"description":"Webhook created successfully.","content":{"application/json":{"schema":{"type":"object","description":"Webhook configuration for receiving real-time email event notifications.\nWhen events occur (delivery, open, click, bounce, etc.), SendPost sends\nHTTP POST requests to your configured webhook URL.\n\n**Best Practices:**\n- Use HTTPS endpoints for security\n- Respond with 2xx status within 10 seconds\n- Implement idempotency using eventId\n- Verify webhook signatures (see documentation)\n","properties":{"id":{"type":"integer","format":"int64","description":"Unique identifier for the webhook configuration","example":117,"uniqueKey":"id","typeLabel":"integer\u003cint64>"},"enabled":{"type":"boolean","description":"Whether the webhook is active. When false, no events will be sent to this webhook.\nUseful for temporarily pausing notifications during maintenance.\n","example":true,"uniqueKey":"enabled","typeLabel":"boolean"},"url":{"type":"string","format":"uri","description":"HTTPS endpoint URL to receive webhook POST requests.\nMust be publicly accessible and return 2xx status code.\n","example":"https://app.hooli.com/api/webhooks/sendpost","uniqueKey":"url","typeLabel":"string\u003curi>"},"processed":{"type":"boolean","description":"Trigger webhook when an email is accepted for processing.\nFires immediately when API call is successful.\n","example":true,"uniqueKey":"processed","typeLabel":"boolean"},"sent":{"type":"boolean","description":"Trigger webhook when an email is sent to the recipient's mail server.\nIndicates the email left SendPost's infrastructure.\n","example":true,"uniqueKey":"sent","typeLabel":"boolean"},"dropped":{"type":"boolean","description":"Trigger webhook when an email is dropped before sending.\nCommon reasons: suppressed address, invalid email, unverified domain.\n","example":true,"uniqueKey":"dropped","typeLabel":"boolean"},"smtpDropped":{"type":"boolean","description":"Trigger webhook when an email is dropped at SMTP level.\nUsually due to policy rejection by receiving server.\n","example":false,"uniqueKey":"smtpDropped","typeLabel":"boolean"},"delivered":{"type":"boolean","description":"Trigger webhook when an email is successfully delivered.\nNote: \"Delivered\" means accepted by mail server, not inbox placement.\n","example":true,"uniqueKey":"delivered","typeLabel":"boolean"},"softBounced":{"type":"boolean","description":"Trigger webhook on temporary delivery failure (soft bounce).\nSendPost will retry delivery automatically.\n","example":true,"uniqueKey":"softBounced","typeLabel":"boolean"},"hardBounced":{"type":"boolean","description":"Trigger webhook on permanent delivery failure (hard bounce).\nThe recipient is automatically added to suppression list.\n","example":true,"uniqueKey":"hardBounced","typeLabel":"boolean"},"opened":{"type":"boolean","description":"Trigger webhook when recipient opens the email.\nFires on every open (can fire multiple times per email).\n","example":true,"uniqueKey":"opened","typeLabel":"boolean"},"clicked":{"type":"boolean","description":"Trigger webhook when recipient clicks a link.\nFires on every click (can fire multiple times per email).\n","example":true,"uniqueKey":"clicked","typeLabel":"boolean"},"unsubscribed":{"type":"boolean","description":"Trigger webhook when recipient clicks the unsubscribe link.\nThe recipient is automatically added to suppression list.\n","example":true,"uniqueKey":"unsubscribed","typeLabel":"boolean"},"spam":{"type":"boolean","description":"Trigger webhook when recipient marks email as spam.\nThe recipient is automatically added to suppression list.\nMonitor this closely - high spam rates damage sender reputation.\n","example":true,"uniqueKey":"spam","typeLabel":"boolean"},"uniqueOpen":{"type":"boolean","description":"Trigger webhook only on the first open of an email (unique opens).\nUse this instead of 'opened' if you only care about unique engagement.\n","example":false,"uniqueKey":"uniqueOpen","typeLabel":"boolean"},"uniqueClick":{"type":"boolean","description":"Trigger webhook only on the first click of an email (unique clicks).\nUse this instead of 'clicked' if you only care about unique engagement.\n","example":false,"uniqueKey":"uniqueClick","typeLabel":"boolean"},"validated":{"type":"boolean","description":"Trigger webhook with the real-time list cleaning result of each email (Validation event, type 82). Needs the Real-Time List Cleaning add-on. Only present in responses when true. See [Real-Time Validation Results](/api-reference/webhook/validation-results).\n","example":true,"uniqueKey":"validated","typeLabel":"boolean"},"status":{"type":"string","description":"Health status of the webhook (read-only):\n- `active` - delivering normally\n- `degraded` - recent delivery failures\n- `disabled` - auto-disabled after repeated consecutive failures\n","enum":["active","degraded","disabled"],"example":"active","uniqueKey":"status","typeLabel":"enum\u003cstring>"},"disabledAt":{"type":"integer","format":"int64","description":"UNIX epoch timestamp in nanoseconds when the webhook was auto-disabled (0 if never). Read-only.","example":0,"uniqueKey":"disabledAt","typeLabel":"integer\u003cint64>"},"disabledReason":{"type":"string","description":"Human-readable reason the webhook was auto-disabled (empty if active). Read-only.","example":"","uniqueKey":"disabledReason","typeLabel":"string"},"created":{"type":"integer","format":"int64","description":"UNIX epoch timestamp in nanoseconds when the webhook was created","example":1704067200000000000,"uniqueKey":"created","typeLabel":"integer\u003cint64>"}},"example":{"id":117,"enabled":true,"url":"https://app.hooli.com/api/webhooks/sendpost","processed":false,"sent":false,"dropped":true,"smtpDropped":false,"delivered":true,"softBounced":true,"hardBounced":true,"opened":true,"clicked":true,"unsubscribed":true,"spam":true,"uniqueOpen":false,"uniqueClick":false,"created":1704067200000000000},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"id":117,"enabled":true,"url":"https://app.hooli.com/api/webhooks/sendpost","processed":false,"sent":false,"dropped":true,"smtpDropped":false,"delivered":true,"softBounced":true,"hardBounced":true,"opened":true,"clicked":true,"unsubscribed":true,"spam":true,"uniqueOpen":false,"uniqueClick":false,"created":1704067200000000000}}},"exampleType":"generated"}},"exampleType":"generated"},"850dcabb-ab89-4bf2-9fc5-ae8d21d0c61b":{"description":"Unauthorized. Invalid or missing API key.","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}},"5045fd89-577e-432d-9fee-bfcf22ee5255":{"description":"Forbidden. Webhook with the same URL already exists.","content":{"application/json":{"schema":{"type":"object","description":"Error body returned by the webhook endpoints.","properties":{"error":{"type":"string","description":"Why the request failed.","example":"url must be an absolute http:// or https:// URL","uniqueKey":"error","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":"url must be an absolute http:// or https:// URL"}}},"exampleType":"generated"}},"exampleType":"generated"},"e4460167-ff7a-4b5f-832e-47a1fab6a74c":{"description":"Not Acceptable. Cannot create webhook for the default sub-account.","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}},"dfa819e6-b77e-4b7e-a7cc-dd9f1c99a47a":{"description":"Unprocessable entity. `url` is missing or isn't an absolute `http://` or `https://` URL, or the body isn't valid JSON. Nothing is created.","content":{"application/json":{"schema":{"type":"object","description":"Error body returned by the webhook endpoints.","properties":{"error":{"type":"string","description":"Why the request failed.","example":"url must be an absolute http:// or https:// URL","uniqueKey":"error","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"example":{"error":"url must be an absolute http:// or https:// URL"},"examples":{"Example":{"title":"Example","value":{"error":"url must be an absolute http:// or https:// URL"}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"48ee9cf2-702c-4c6a-9911-b8595eca14b2":{"accountAuth":{"type":"apiKey","in":"header","name":"X-Account-ApiKey","description":"This api key can be used for all account level operations","scopes":[],"schemeName":"accountAuth"}}},"servers":{"3e2bf5d9-3b9c-4724-ba94-ee3efb46f2dc":{"url":"https://api.sendpost.io/api/v1"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"X-Account-ApiKey","description":"This api key can be used for all account level operations","scopes":[],"schemeName":"accountAuth"},"schema":{"title":"X-Account-ApiKey","type":"string","description":"This api key can be used for all account level operations","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"accountAuth","name":"X-Account-ApiKey"}],"title":"accountAuth"}]},"originalFileLocation":"swagger.yaml"},"subdomain":"sendx-43e2b6a9","siteName":"SendPost Docs","title":"Create Webhook - SendPost Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-22T09:59:55.136Z","originalFileLocation":"api-reference/webhook/create-a-new-webhook.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Create a new webhook to receive real-time notifications for email events. Your endpoint will receive HTTP POST requests with event data as they occur. Endpoint Requirements: - Must be a publicly accessible absolute http:// or https:// URL (use HTTPS) - Should return 2xx status within 30 seconds - Handle potential duplicate events (use event ID for deduplication) - Implement retry/queue logic for reliability Choosing Events: - Engagement Tracking: uniqueOpened, uniqueClicked for metrics - Full History: opened, clicked for complete event logs - Delivery Monitoring: delivered, hardBounced, softBounced - Compliance: unsubscribed, spam Best Practices: - Only enable events you actually need - Store events before processing (async processing) - Implement idempotency using event IDs - Set up monitoring for webhook failures Webhook Payload Example: json { \u0026quot;eventId\u0026quot;: \u0026quot;evt_123\u0026quot;, \u0026quot;event\u0026quot;: \u0026quot;delivered\u0026quot;, \u0026quot;messageId\u0026quot;: \u0026quot;msg_456\u0026quot;, \u0026quot;recipient\u0026quot;: \u0026quot;user@example.com\u0026quot;, \u0026quot;timestamp\u0026quot;: \u0026quot;2024-01-15T10:30:00Z\u0026quot; }\">\u003cmeta data-mint-head name=\"application-name\" content=\"SendPost Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/sendx-43e2b6a9/gASVnBX9Wp6ly5V-/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/sendx-43e2b6a9/gASVnBX9Wp6ly5V-/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/sendx-43e2b6a9/gASVnBX9Wp6ly5V-/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/sendx-43e2b6a9/gASVnBX9Wp6ly5V-/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/sendx-43e2b6a9/gASVnBX9Wp6ly5V-/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/sendx-43e2b6a9/gASVnBX9Wp6ly5V-/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/sendx-43e2b6a9/gASVnBX9Wp6ly5V-/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/sendx-43e2b6a9/gASVnBX9Wp6ly5V-/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/sendx-43e2b6a9/gASVnBX9Wp6ly5V-/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create Webhook - SendPost Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create a new webhook to receive real-time notifications for email events. Your endpoint will receive HTTP POST requests with event data as they occur. Endpoint Requirements: - Must be a publicly accessible absolute http:// or https:// URL (use HTTPS) - Should return 2xx status within 30 seconds - Handle potential duplicate events (use event ID for deduplication) - Implement retry/queue logic for reliability Choosing Events: - Engagement Tracking: uniqueOpened, uniqueClicked for metrics - Full History: opened, clicked for complete event logs - Delivery Monitoring: delivered, hardBounced, softBounced - Compliance: unsubscribed, spam Best Practices: - Only enable events you actually need - Store events before processing (async processing) - Implement idempotency using event IDs - Set up monitoring for webhook failures Webhook Payload Example: json { \u0026quot;eventId\u0026quot;: \u0026quot;evt_123\u0026quot;, \u0026quot;event\u0026quot;: \u0026quot;delivered\u0026quot;, \u0026quot;messageId\u0026quot;: \u0026quot;msg_456\u0026quot;, \u0026quot;recipient\u0026quot;: \u0026quot;user@example.com\u0026quot;, \u0026quot;timestamp\u0026quot;: \u0026quot;2024-01-15T10:30:00Z\u0026quot; }\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"SendPost Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.sendpost.io/api-reference/webhook/create-a-new-webhook\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://sendx-43e2b6a9.mintlify.site/_mintlify/api/og/v2?division=Webhook\u0026amp;title=Create+Webhook\u0026amp;description=Create+a+new+webhook+to+receive+real-time+notifications+for+email+events.+Your+endpoint+will+receive+HTTP+POST+requests+with+event+data+as+they+occur.%0A%0A**Endpoi\u0026amp;theme=36b9a144c81c41c7c881e1e9\u0026amp;signature=04776e95c7e4e32734519cc1b1a13645776cc4cd1853927cb7563609113d2a00\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create Webhook - SendPost Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create a new webhook to receive real-time notifications for email events. Your endpoint will receive HTTP POST requests with event data as they occur. Endpoint Requirements: - Must be a publicly accessible absolute http:// or https:// URL (use HTTPS) - Should return 2xx status within 30 seconds - Handle potential duplicate events (use event ID for deduplication) - Implement retry/queue logic for reliability Choosing Events: - Engagement Tracking: uniqueOpened, uniqueClicked for metrics - Full History: opened, clicked for complete event logs - Delivery Monitoring: delivered, hardBounced, softBounced - Compliance: unsubscribed, spam Best Practices: - Only enable events you actually need - Store events before processing (async processing) - Implement idempotency using event IDs - Set up monitoring for webhook failures Webhook Payload Example: json { \u0026quot;eventId\u0026quot;: \u0026quot;evt_123\u0026quot;, \u0026quot;event\u0026quot;: \u0026quot;delivered\u0026quot;, \u0026quot;messageId\u0026quot;: \u0026quot;msg_456\u0026quot;, \u0026quot;recipient\u0026quot;: \u0026quot;user@example.com\u0026quot;, \u0026quot;timestamp\u0026quot;: \u0026quot;2024-01-15T10:30:00Z\u0026quot; }\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://sendx-43e2b6a9.mintlify.site/_mintlify/api/og/v2?division=Webhook\u0026amp;title=Create+Webhook\u0026amp;description=Create+a+new+webhook+to+receive+real-time+notifications+for+email+events.+Your+endpoint+will+receive+HTTP+POST+requests+with+event+data+as+they+occur.%0A%0A**Endpoi\u0026amp;theme=36b9a144c81c41c7c881e1e9\u0026amp;signature=04776e95c7e4e32734519cc1b1a13645776cc4cd1853927cb7563609113d2a00\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/sendx-43e2b6a9/gASVnBX9Wp6ly5V-/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"SendPost Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#5750EC\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.sendpost.io/api-reference/webhook/create-a-new-webhook\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/webhook/create-a-new-webhook.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.sendpost.io/#organization\",\"name\":\"SendPost Docs\",\"url\":\"https://docs.sendpost.io\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/sendx-43e2b6a9/xWJ6M32vFagLUxJg/logo/sendpost.svg?fit=max\u0026auto=format\u0026n=xWJ6M32vFagLUxJg\u0026q=85\u0026s=fc1d92fba901bca2cbab1ee394bc02ed\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.sendpost.io#website\",\"name\":\"SendPost Docs\",\"url\":\"https://docs.sendpost.io\",\"publisher\":{\"@id\":\"https://docs.sendpost.io/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.sendpost.io/api-reference/webhook/create-a-new-webhook#webpage\",\"url\":\"https://docs.sendpost.io/api-reference/webhook/create-a-new-webhook\",\"name\":\"Create Webhook\",\"description\":\"Create a new webhook to receive real-time notifications for email events. Your endpoint will receive HTTP POST requests with event data as they occur. Endpoint Requirements: - Must be a publicly accessible absolute http:// or https:// URL (use HTTPS) - Should return 2xx status within 30 seconds - Handle potential duplicate events (use event ID for deduplication) - Implement retry/queue logic for reliability Choosing Events: - Engagement Tracking: uniqueOpened, uniqueClicked for metrics - Full History: opened, clicked for complete event logs - Delivery Monitoring: delivered, hardBounced, softBounced - Compliance: unsubscribed, spam Best Practices: - Only enable events you actually need - Store events before processing (async processing) - Implement idempotency using event IDs - Set up monitoring for webhook failures Webhook Payload Example: json { \\\"eventId\\\": \\\"evt_123\\\", \\\"event\\\": \\\"delivered\\\", \\\"messageId\\\": \\\"msg_456\\\", \\\"recipient\\\": \\\"user@example.com\\\", \\\"timestamp\\\": \\\"2024-01-15T10:30:00Z\\\" }\",\"dateModified\":\"2026-10-22T09:59:55.136Z\",\"isPartOf\":{\"@id\":\"https://docs.sendpost.io#website\"},\"breadcrumb\":{\"@id\":\"https://docs.sendpost.io/api-reference/webhook/create-a-new-webhook#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.sendpost.io/api-reference/webhook/create-a-new-webhook#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Webhook\",\"item\":\"https://docs.sendpost.io/api-reference/webhook/webhook-testing\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create Webhook\",\"item\":\"https://docs.sendpost.io/api-reference/webhook/create-a-new-webhook\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.sendpost.io/api-reference/webhook/create-a-new-webhook#apireference\",\"headline\":\"Create Webhook\",\"name\":\"Create Webhook\",\"description\":\"Create a new webhook to receive real-time notifications for email events. Your endpoint will receive HTTP POST requests with event data as they occur. Endpoint Requirements: - Must be a publicly accessible absolute http:// or https:// URL (use HTTPS) - Should return 2xx status within 30 seconds - Handle potential duplicate events (use event ID for deduplication) - Implement retry/queue logic for reliability Choosing Events: - Engagement Tracking: uniqueOpened, uniqueClicked for metrics - Full History: opened, clicked for complete event logs - Delivery Monitoring: delivered, hardBounced, softBounced - Compliance: unsubscribed, spam Best Practices: - Only enable events you actually need - Store events before processing (async processing) - Implement idempotency using event IDs - Set up monitoring for webhook failures Webhook Payload Example: json { \\\"eventId\\\": \\\"evt_123\\\", \\\"event\\\": \\\"delivered\\\", \\\"messageId\\\": \\\"msg_456\\\", \\\"recipient\\\": \\\"user@example.com\\\", \\\"timestamp\\\": \\\"2024-01-15T10:30:00Z\\\" }\",\"url\":\"https://docs.sendpost.io/api-reference/webhook/create-a-new-webhook\",\"mainEntityOfPage\":{\"@id\":\"https://docs.sendpost.io/api-reference/webhook/create-a-new-webhook#webpage\"},\"dateModified\":\"2026-10-22T09:59:55.136Z\",\"publisher\":{\"@id\":\"https://docs.sendpost.io/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.sendpost.io#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"SendPost Docs\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"SendPost Docs","nav":{"global":{"anchors":[]},"tabs":[{"tab":"Welcome","pages":[{"title":"Welcome","href":""}]},{"tab":"API Reference","groups":[{"group":"API Reference","pages":[{"title":"Introduction","href":"/api-reference/introduction"},{"title":"API Versioning \u0026 Migration","href":"/api-reference/api-versioning"},{"title":"Changelog","href":"/api-reference/changelog"}]},{"group":"Email","pages":[{"openapi":"post /subaccount/email/","title":"Send Email","href":"/api-reference/email/send-email"},{"openapi":"post /subaccount/email/template","title":"Send Email With Template","href":"/api-reference/email/send-email-with-template"}]},{"group":"Domain","pages":[{"openapi":"get /subaccount/domain/{domain_id}","title":"Get Domain","href":"/api-reference/domain/get-a-specific-domain"},{"openapi":"delete /subaccount/domain/{domain_id}","title":"Delete Domain","href":"/api-reference/domain/delete-a-specific-domain"},{"openapi":"get /subaccount/domain","title":"List Domains","href":"/api-reference/domain/get-all-domains"},{"openapi":"post /subaccount/domain","title":"Create Domain","href":"/api-reference/domain/create-a-new-domain"}]},{"group":"Stats","pages":[{"openapi":"get /account/subaccount/stat/{subaccount_id}","title":"List Stats","href":"/api-reference/stats/get-all-stats"},{"openapi":"get /account/subaccount/stat/{subaccount_id}/aggregate","title":"Get Aggregate Stats","href":"/api-reference/stats/get-aggregate-stats"},{"openapi":"get /account/subaccount/stat/{subaccount_id}/group","title":"Get Group Aggregate Stats","href":"/api-reference/stats/get-aggregated-stats-by-group"}]},{"group":"Suppression","pages":[{"openapi":"get /subaccount/suppression","title":"List Suppressions","href":"/api-reference/suppression/get-all-suppressions"},{"openapi":"post /subaccount/suppression","title":"Create Suppressions","href":"/api-reference/suppression/create-new-suppressions"},{"openapi":"delete /subaccount/suppression","title":"Delete Suppressions","href":"/api-reference/suppression/delete-suppressions"}]},{"group":"IP","pages":[{"openapi":"get /account/ip/","title":"List IPs","href":"/api-reference/ip/get-all-ips"},{"openapi":"get /account/ip/{ip_id}","title":"Get IP","href":"/api-reference/ip/get-a-specific-ip"},{"openapi":"put /account/ip/{ip_id}","title":"Update IP","href":"/api-reference/ip/update-an-existing-ip"},{"openapi":"delete /account/ip/{ip_id}","title":"Delete IP","href":"/api-reference/ip/delete-a-specific-ip"},{"openapi":"put /account/ip/allocate","title":"Allocate IP","href":"/api-reference/ip/allocate-a-new-ip"}]},{"group":"Message","pages":[{"openapi":"get /account/message/{message_id}","title":"Get Message","href":"/api-reference/message/retrieve-a-specific-message"}]},{"group":"IPPools","pages":[{"title":"Routing Strategies and Metadata","href":"/api-reference/ippools/routing"},{"openapi":"get /account/ippool","title":"List IPPools","href":"/api-reference/ippools/get-all-ippools"},{"openapi":"post /account/ippool","title":"Create IPPool","href":"/api-reference/ippools/create-a-new-ippool"},{"openapi":"get /account/ippool/{ippool_id}","title":"Get IPPool","href":"/api-reference/ippools/get-a-specific-ippool"},{"openapi":"put /account/ippool/{ippool_id}","title":"Update IPPool","href":"/api-reference/ippools/update-an-existing-ippool"},{"openapi":"delete /account/ippool/{ippool_id}","title":"Delete IPPool","href":"/api-reference/ippools/delete-a-specific-ippool"}]},{"group":"Stats (A)","pages":[{"openapi":"get /account/stat","title":"List Account Stats","href":"/api-reference/stats-a/get-all-account-stats"},{"openapi":"get /account/stat/aggregate","title":"Get Account Aggregate Stats","href":"/api-reference/stats-a/get-account-aggregate-stats"},{"openapi":"get /account/stat/group","title":"List Account Group Stats","href":"/api-reference/stats-a/get-all-account-stats-by-group"},{"openapi":"get /account/stat/aggregate/group","title":"Get Account Group Aggregate Stats","href":"/api-reference/stats-a/get-account-aggregate-stats-by-group"}]},{"group":"Sub-Account","pages":[{"openapi":"get /account/subaccount/","title":"List Sub-Accounts","href":"/api-reference/sub-account/get-all-sub-accounts"},{"openapi":"post /account/subaccount/","title":"Create Sub-Account","href":"/api-reference/sub-account/create-a-new-sub-account"},{"openapi":"get /account/subaccount/{subaccount_id}","title":"Get Sub-Account","href":"/api-reference/sub-account/get-a-specific-sub-account"},{"openapi":"put /account/subaccount/{subaccount_id}","title":"Update Sub-Account","href":"/api-reference/sub-account/update-an-existing-sub-account"},{"openapi":"delete /account/subaccount/{subaccount_id}","title":"Delete Sub-Account","href":"/api-reference/sub-account/delete-a-specific-sub-account"}]},{"group":"Webhook","pages":[{"title":"Webhook Reference","href":"/api-reference/webhook/webhook-testing"},{"title":"Understanding Webhook Event Lifecycle","href":"/api-reference/webhook/understanding-webhook-event-lifecycle"},{"title":"Real-Time Validation Results","href":"/api-reference/webhook/validation-results"},{"title":"Webhook Signature Verification","href":"/api-reference/webhook/webhook-signature-verification"},{"openapi":"get /account/webhook","title":"List Webhooks","description":"Retrieve all configured webhooks for your account. Webhooks enable real-time notifications when email events occur, allowing you to build reactive applications.\n\n**Supported Events:**\n| Event | Description |\n|-------|-------------|\n| `processed` | Email accepted and queued for delivery |\n| `dropped` | Email blocked (suppressed, invalid, policy) |\n| `delivered` | Email successfully delivered to recipient |\n| `hardBounced` | Permanent delivery failure |\n| `softBounced` | Temporary delivery failure |\n| `opened` | Recipient opened the email (all opens) |\n| `uniqueOpened` | First open per recipient only |\n| `clicked` | Recipient clicked a link (all clicks) |\n| `uniqueClicked` | First click per recipient only |\n| `unsubscribed` | Recipient unsubscribed |\n| `spam` | Recipient marked email as spam |\n\n**Use Cases:**\n- Audit configured webhook endpoints\n- Verify webhook URLs are correct\n- Review enabled events per webhook\n- Debug webhook delivery issues\n","href":"/api-reference/webhook/get-all-webhooks"},{"openapi":"post /account/webhook","title":"Create Webhook","href":"/api-reference/webhook/create-a-new-webhook"},{"openapi":"get /account/webhook/{webhook_id}","title":"Get Webhook","description":"Retrieve detailed information about a specific webhook, including its endpoint URL and enabled events.\n\n**Use Cases:**\n- Verify webhook configuration\n- Debug event delivery issues\n- Check enabled events for a webhook\n- Audit webhook settings\n","href":"/api-reference/webhook/get-a-specific-webhook"},{"openapi":"put /account/webhook/{webhook_id}","title":"Update Webhook","href":"/api-reference/webhook/update-an-existing-webhook"},{"openapi":"delete /account/webhook/{webhook_id}","title":"Delete Webhook","href":"/api-reference/webhook/delete-a-specific-webhook"},{"openapi":"webhook SendPostWebhooks","title":"SendPost Webhook Object","href":"/api-reference/webhook/sendpost-webhook-object"}]}]}]},"basePath":"","title":"Create Webhook - SendPost Docs","buildId":"dpl_42LwxxU1kGN114H4XzwGYXa9ZDah","deploymentId":"dpl_42LwxxU1kGN114H4XzwGYXa9ZDah","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-C-hEh3I2.js","utils-CnF4QiUD.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-C7PVNbel.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-8ytevL2A.js","snippetPresets-BT1alx3v.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-BLXC0i_W.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-CyLIGI9_.js","shallow-DC0lGVIW.js","getApiPlaygroundDisplay-CgDQ85tN.js","CodeSnippet-6-I-Gpv9.js","CodeSnippets-BAk1kDdu.js","Page-C945cI-W.js","getPastedJson-B276RuWN.js","icon-BqP8etTm.js","MethodPill-DM6sbxG1.js","DuplicateIcon-PyJglOaE.js","createIcon-CMeOMAc_.js","DynamicMarkdown-BoyYAA8K.js","SectionHeading-DAYv3gvZ.js","axios-vUo_bRtp.js","Markdown-BhTTmazV.js","clsx-CR-RHrVC.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-CBUH0-zX.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-BmARFYNC.js"]}