[{"data":1,"prerenderedAt":14},["ShallowReactive",2],{"$f28kXZukr2kIfYevZkY0yjuqFpZyHHvvwptU8nt07FVY":3},{"title":4,"slug":5,"excerpt":6,"category":7,"order":8,"description":9,"screens":10,"html":13},"Atomic webhook and alias endpoint","webhook-alias-atomic-endpoint","Create a webhook and email alias in a single API call with automatic linking","integrations",3,"Create a webhook and email alias in a single atomic API call with smart create\u002Fupdate behavior",[11,12],"webhooks","aliases","\u003Cp>The atomic webhook\u002Falias endpoint lets you create a webhook and email alias in a single API call. Both resources are created together in a transaction — if either fails, neither is created. This is the recommended way to set up email forwarding programmatically.\u003C\u002Fp>\n\u003Ch2>Endpoint\u003C\u002Fh2>\n\u003Cpre>\u003Ccode>POST https:\u002F\u002Fapp.emailconnect.eu\u002Fapi\u002Fwebhooks\u002Falias\nX-API-KEY: YOUR_API_KEY\nContent-Type: application\u002Fjson\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2>Request body\u003C\u002Fh2>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Field\u003C\u002Fth>\n\u003Cth>Type\u003C\u002Fth>\n\u003Cth>Required\u003C\u002Fth>\n\u003Cth>Description\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Ccode>domainId\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>string\u003C\u002Ftd>\n\u003Ctd>Yes\u003C\u002Ftd>\n\u003Ctd>ID of the domain to create the alias under\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>webhookUrl\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>string\u003C\u002Ftd>\n\u003Ctd>Yes\u003C\u002Ftd>\n\u003Ctd>URL to receive webhook payloads (must be a valid URI)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>webhookName\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>string\u003C\u002Ftd>\n\u003Ctd>Yes\u003C\u002Ftd>\n\u003Ctd>Display name for the webhook (1–100 characters)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>webhookDescription\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>string\u003C\u002Ftd>\n\u003Ctd>No\u003C\u002Ftd>\n\u003Ctd>Optional description (max 500 characters)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>aliasType\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>string\u003C\u002Ftd>\n\u003Ctd>Yes\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>"catchall"\u003C\u002Fcode> or \u003Ccode>"specific"\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>localPart\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>string\u003C\u002Ftd>\n\u003Ctd>Conditional\u003C\u002Ftd>\n\u003Ctd>Required when \u003Ccode>aliasType\u003C\u002Fcode> is \u003Ccode>"specific"\u003C\u002Fcode>. The part before the \u003Ccode>@\u003C\u002Fcode> (1–64 characters)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>syncWithDomain\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>boolean\u003C\u002Ftd>\n\u003Ctd>No\u003C\u002Ftd>\n\u003Ctd>Sync catch-all webhook with domain default. Default: \u003Ccode>true\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>firstOrCreate\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>boolean\u003C\u002Ftd>\n\u003Ctd>No\u003C\u002Ftd>\n\u003Ctd>Smart create\u002Fupdate — reuse existing alias if found. Default: \u003Ccode>false\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>updateWebhookData\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>boolean\u003C\u002Ftd>\n\u003Ctd>No\u003C\u002Ftd>\n\u003Ctd>Update webhook name\u002FURL if alias already exists. Default: \u003Ccode>true\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>generateSecret\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>boolean\u003C\u002Ftd>\n\u003Ctd>No\u003C\u002Ftd>\n\u003Ctd>Generate webhook signing secret (Business plan required). Default: \u003Ccode>false\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>webhookSecret\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>string\u003C\u002Ftd>\n\u003Ctd>No\u003C\u002Ftd>\n\u003Ctd>Provide your own signing secret (Business plan required)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\n\u003Ch2>Basic example\u003C\u002Fh2>\n\u003Ch3>Node.js\u003C\u002Fh3>\n\u003Cpre>\u003Ccode class=\"language-javascript\">const response = await fetch('https:\u002F\u002Fapp.emailconnect.eu\u002Fapi\u002Fwebhooks\u002Falias', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson'\n  },\n  body: JSON.stringify({\n    domainId: 'dom_abc123',\n    webhookUrl: 'https:\u002F\u002Fyour-app.com\u002Fwebhook\u002Femails',\n    webhookName: 'My email webhook',\n    aliasType: 'specific',\n    localPart: 'support'\n  })\n});\n\nconst result = await response.json();\n\u002F\u002F result.alias.email → "support@yourdomain.com"\n\u002F\u002F result.webhook.id → "wh_xyz789"\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3>Python\u003C\u002Fh3>\n\u003Cpre>\u003Ccode class=\"language-python\">import requests\n\nresponse = requests.post(\n    'https:\u002F\u002Fapp.emailconnect.eu\u002Fapi\u002Fwebhooks\u002Falias',\n    headers={\n        'X-API-KEY': 'YOUR_API_KEY',\n        'Content-Type': 'application\u002Fjson'\n    },\n    json={\n        'domainId': 'dom_abc123',\n        'webhookUrl': 'https:\u002F\u002Fyour-app.com\u002Fwebhook\u002Femails',\n        'webhookName': 'My email webhook',\n        'aliasType': 'specific',\n        'localPart': 'support'\n    }\n)\n\nresult = response.json()\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3>cURL\u003C\u002Fh3>\n\u003Cpre>\u003Ccode class=\"language-bash\">curl -X POST https:\u002F\u002Fapp.emailconnect.eu\u002Fapi\u002Fwebhooks\u002Falias \\\n  -H "X-API-KEY: YOUR_API_KEY" \\\n  -H "Content-Type: application\u002Fjson" \\\n  -d '{\n    "domainId": "dom_abc123",\n    "webhookUrl": "https:\u002F\u002Fyour-app.com\u002Fwebhook\u002Femails",\n    "webhookName": "My email webhook",\n    "aliasType": "specific",\n    "localPart": "support"\n  }'\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2>Response\u003C\u002Fh2>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n  "success": true,\n  "webhook": {\n    "id": "wh_xyz789",\n    "name": "My email webhook",\n    "url": "https:\u002F\u002Fyour-app.com\u002Fwebhook\u002Femails",\n    "verified": false,\n    "hasSecret": false,\n    "verificationToken": "abc12",\n    "createdAt": "2026-02-03T12:00:00.000Z"\n  },\n  "alias": {\n    "id": "al_def456",\n    "email": "support@yourdomain.com",\n    "active": true,\n    "createdAt": "2026-02-03T12:00:00.000Z"\n  },\n  "action": "created",\n  "message": "Webhook and alias created successfully"\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2>Response fields\u003C\u002Fh2>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Field\u003C\u002Fth>\n\u003Cth>Description\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Ccode>action\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>One of \u003Ccode>"created"\u003C\u002Fcode>, \u003Ccode>"updated"\u003C\u002Fcode>, \u003Ccode>"webhook_added"\u003C\u002Fcode>, or \u003Ccode>"cross_domain_update"\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>webhook.verified\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Whether the webhook URL has been verified\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>webhook.verificationToken\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Present only if webhook is not yet verified — use to complete verification\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>webhook.hasSecret\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Whether webhook signing is enabled\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>webhookSecret\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Present only once when \u003Ccode>generateSecret\u003C\u002Fcode> is \u003Ccode>true\u003C\u002Fcode> — save it immediately\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\n\u003Ch2>Smart create\u002Fupdate with firstOrCreate\u003C\u002Fh2>\n\u003Cp>When \u003Ccode>firstOrCreate\u003C\u002Fcode> is \u003Ccode>true\u003C\u002Fcode>, the endpoint checks if a matching alias already exists — even across domains. This prevents duplicate aliases and simplifies integration setup.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Behavior by scenario:\u003C\u002Fstrong>\u003C\u002Fp>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Scenario\u003C\u002Fth>\n\u003Cth>Result\u003C\u002Fth>\n\u003Cth>\u003Ccode>action\u003C\u002Fcode> value\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>No existing alias\u003C\u002Ftd>\n\u003Ctd>Creates new webhook + alias\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>"created"\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Alias exists in same domain\u003C\u002Ftd>\n\u003Ctd>Updates webhook details\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>"updated"\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Alias exists in different domain\u003C\u002Ftd>\n\u003Ctd>Moves alias to target domain\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>"cross_domain_update"\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Alias exists without webhook\u003C\u002Ftd>\n\u003Ctd>Creates and links new webhook\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>"webhook_added"\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\n\u003Ch3>Example with firstOrCreate\u003C\u002Fh3>\n\u003Cpre>\u003Ccode class=\"language-bash\">curl -X POST https:\u002F\u002Fapp.emailconnect.eu\u002Fapi\u002Fwebhooks\u002Falias \\\n  -H "X-API-KEY: YOUR_API_KEY" \\\n  -H "Content-Type: application\u002Fjson" \\\n  -d '{\n    "domainId": "dom_abc123",\n    "webhookUrl": "https:\u002F\u002Fyour-app.com\u002Fwebhook\u002Femails",\n    "webhookName": "Updated webhook",\n    "aliasType": "specific",\n    "localPart": "support",\n    "firstOrCreate": true\n  }'\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2>Catch-all aliases\u003C\u002Fh2>\n\u003Cp>Set \u003Ccode>aliasType\u003C\u002Fcode> to \u003Ccode>"catchall"\u003C\u002Fcode> to create a catch-all alias that receives all unmatched emails for a domain.\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n  "domainId": "dom_abc123",\n  "webhookUrl": "https:\u002F\u002Fyour-app.com\u002Fwebhook\u002Femails",\n  "webhookName": "Catch-all webhook",\n  "aliasType": "catchall",\n  "syncWithDomain": true\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>When \u003Ccode>syncWithDomain\u003C\u002Fcode> is \u003Ccode>true\u003C\u002Fcode> (the default), the domain's default webhook is also updated to point to this URL.\u003C\u002Fp>\n\u003Ch2>Webhook signing\u003C\u002Fh2>\n\u003Cp>Add webhook signing (Standard Webhooks) to verify webhook authenticity. Requires a Business plan.\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n  "domainId": "dom_abc123",\n  "webhookUrl": "https:\u002F\u002Fyour-app.com\u002Fwebhook\u002Femails",\n  "webhookName": "Signed webhook",\n  "aliasType": "specific",\n  "localPart": "secure",\n  "generateSecret": true\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>The response will include a \u003Ccode>webhookSecret\u003C\u002Fcode> field. Save it immediately — it will not be shown again. See \u003Ca href=\"\u002Fhelp\u002Fwebhook-signing\u002F\">Webhook signing\u003C\u002Fa> for verification details.\u003C\u002Fp>\n\u003Ch2>Error responses\u003C\u002Fh2>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Status\u003C\u002Fth>\n\u003Cth>Reason\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>400\u003C\u002Ftd>\n\u003Ctd>Invalid request body or missing required fields\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>402\u003C\u002Ftd>\n\u003Ctd>Plan limit exceeded (webhook or alias count) or Business feature required\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>404\u003C\u002Ftd>\n\u003Ctd>Domain not found or access denied\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>409\u003C\u002Ftd>\n\u003Ctd>Alias already exists (when \u003Ccode>firstOrCreate\u003C\u002Fcode> is \u003Ccode>false\u003C\u002Fcode>)\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\n\u003Ch2>Related\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>\u003Ca href=\"\u002Fhelp\u002Fapi-keys-integrations\u002F\">API keys and integrations\u003C\u002Fa> — managing API keys\u003C\u002Fli>\n\u003Cli>\u003Ca href=\"\u002Fhelp\u002Fwebhook-signing\u002F\">Webhook signing\u003C\u002Fa> — verifying webhook signatures\u003C\u002Fli>\n\u003Cli>\u003Ca href=\"\u002Fhelp\u002Fwebhook-configuration\u002F\">Webhook configuration\u003C\u002Fa> — general webhook setup\u003C\u002Fli>\n\u003C\u002Ful>\n",1781207681771]