[{"data":1,"prerenderedAt":12},["ShallowReactive",2],{"$f2EvDxK8xRHoFWbFg8YDKcOSXI4tfI6XSZ0JJzAc3YNQ":3},{"title":4,"slug":5,"excerpt":6,"category":7,"order":8,"screens":9,"html":11},"Webhook configuration","webhook-configuration","Learn how to set up and configure webhooks to receive processed email data","configuration",3,[10],"webhooks","\u003Cp>Webhooks are HTTP endpoints that receive processed email data from EmailConnect. This guide covers everything you need to know about setting up and managing webhooks.\u003C\u002Fp>\n\u003Ch2>What are webhooks?\u003C\u002Fh2>\n\u003Cp>When an email is received by EmailConnect, it's processed and sent as an HTTP POST request to your webhook URL. This allows your application to:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Receive email data in real-time\u003C\u002Fli>\n\u003Cli>Process emails programmatically\u003C\u002Fli>\n\u003Cli>Integrate with existing systems\u003C\u002Fli>\n\u003Cli>Trigger automated workflows\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2>Webhook data format\u003C\u002Fh2>\n\u003Cp>EmailConnect sends email data in JSON format:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n  "spam": {\n    "score": -0.99,\n    "isSpam": false,\n    "action": "default"\n  },\n  "message": {\n    "date": "2026-02-12T10:30:00.000Z",\n    "sender": {\n      "name": "Alice Martin",\n      "email": "alice@example.com"\n    },\n    "content": {\n      "text": "Hi team,\\n\\nPlease find the report attached.\\n\\nBest,\\nAlice",\n      "html": "<p>Hi team,<\u002Fp><p>Please find the report attached.<\u002Fp><p>Best,<br>Alice<\u002Fp>",\n      "markdown": "Hi team,\\n\\nPlease find the report attached.\\n\\nBest,\\nAlice",\n      "links": []\n    },\n    "subject": "Monthly report attached",\n    "recipient": {\n      "name": null,\n      "email": "reports@yourdomain.com"\n    },\n    "attachments": []\n  },\n  "integrity": {\n    "contentHash": "a3f2b8c1...",\n    "rawEmailHash": "9f8e7d6c..."\n  },\n  "classification": {\n    "type": "normal",\n    "confidence": "definite",\n    "signals": ["single_recipient"]\n  },\n  "security": {\n    "virusScan": {\n      "scanned": true,\n      "threatsFound": 0\n    }\n  }\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2>Setting up webhooks\u003C\u002Fh2>\n\u003Ch3>1. Create a webhook endpoint\u003C\u002Fh3>\n\u003Cp>Your webhook endpoint should:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Accept HTTP POST requests\u003C\u002Fli>\n\u003Cli>Return a 200 status code for successful processing\u003C\u002Fli>\n\u003Cli>Process requests within 30 seconds (timeout limit)\u003C\u002Fli>\n\u003Cli>Handle JSON content type\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>\u003Cstrong>Example webhook endpoint (Node.js\u002FExpress):\u003C\u002Fstrong>\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-javascript\">app.post('\u002Fwebhook\u002Femails', (req, res) => {\n  const emailData = req.body;\n  \n  \u002F\u002F Process the email data\n  console.log('Received email:', emailData.subject);\n  \n  \u002F\u002F Your processing logic here\n  processEmail(emailData);\n  \n  \u002F\u002F Return success response\n  res.status(200).json({ success: true });\n});\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3>2. Add webhook in dashboard\u003C\u002Fh3>\n\u003Col>\n\u003Cli>Go to \u003Cstrong>Webhooks\u003C\u002Fstrong> in your dashboard\u003C\u002Fli>\n\u003Cli>Click \u003Cstrong>Create Webhook\u003C\u002Fstrong>\u003C\u002Fli>\n\u003Cli>Enter your webhook URL\u003C\u002Fli>\n\u003Cli>Choose which events to receive\u003C\u002Fli>\n\u003Cli>Test the webhook connection\u003C\u002Fli>\n\u003Cli>Save the webhook\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Ch3>3. Configure webhook security\u003C\u002Fh3>\n\u003Cp>\u003Cstrong>Webhook Signatures:\u003C\u002Fstrong>\nEmailConnect signs webhook requests following the \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fstandard-webhooks\u002Fstandard-webhooks\">Standard Webhooks\u003C\u002Fa> convention. Verify signatures to ensure requests are authentic:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-javascript\">const crypto = require('crypto');\n\nfunction verifyWebhook(headers, rawBody, secret) {\n  const signedContent = `${headers['webhook-id']}.${headers['webhook-timestamp']}.${rawBody}`;\n  const secretBytes = Buffer.from(secret.replace(\u002F^whsec_\u002F, ''), 'base64');\n  const expected = crypto.createHmac('sha256', secretBytes).update(signedContent).digest('base64');\n\n  return headers['webhook-signature'].split(' ').some(sig => {\n    const [v, val] = sig.split(',');\n    return v === 'v1' && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(val));\n  });\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2>Webhook events\u003C\u002Fh2>\n\u003Cp>Configure which events trigger webhook calls:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Email Received\u003C\u002Fstrong>: New email processed\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Delivery Failed\u003C\u002Fstrong>: Email processing failed\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Bounce Received\u003C\u002Fstrong>: Bounce notification received\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Spam Detected\u003C\u002Fstrong>: Email marked as spam\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2>Testing webhooks\u003C\u002Fh2>\n\u003Ch3>Built-in testing\u003C\u002Fh3>\n\u003Cp>Use the webhook testing feature in your dashboard:\u003C\u002Fp>\n\u003Col>\n\u003Cli>Go to your webhook configuration\u003C\u002Fli>\n\u003Cli>Click \u003Cstrong>Test Webhook\u003C\u002Fstrong>\u003C\u002Fli>\n\u003Cli>Review the test response\u003C\u002Fli>\n\u003Cli>Check your endpoint logs\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Ch3>Manual testing\u003C\u002Fh3>\n\u003Cp>Send a test email to your alias and monitor:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Your webhook endpoint logs\u003C\u002Fli>\n\u003Cli>EmailConnect delivery logs\u003C\u002Fli>\n\u003Cli>Response times and status codes\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2>Best practices\u003C\u002Fh2>\n\u003Ch3>Reliability\u003C\u002Fh3>\n\u003Cul>\n\u003Cli>\u003Cstrong>Idempotency\u003C\u002Fstrong>: Handle duplicate webhook calls gracefully\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Timeouts\u003C\u002Fstrong>: Respond within 30 seconds to avoid retries\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Error Handling\u003C\u002Fstrong>: Return appropriate HTTP status codes\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Logging\u003C\u002Fstrong>: Log all webhook requests for debugging\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch3>Security\u003C\u002Fh3>\n\u003Cul>\n\u003Cli>\u003Cstrong>HTTPS Only\u003C\u002Fstrong>: Always use HTTPS for webhook URLs\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Signature Verification\u003C\u002Fstrong>: Verify webhook signatures\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Rate Limiting\u003C\u002Fstrong>: Implement rate limiting on your endpoint\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch3>Performance\u003C\u002Fh3>\n\u003Cul>\n\u003Cli>\u003Cstrong>Async Processing\u003C\u002Fstrong>: Process emails asynchronously when possible\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Queue Systems\u003C\u002Fstrong>: Use queues for heavy processing\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Database Optimization\u003C\u002Fstrong>: Optimize database operations\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Monitoring\u003C\u002Fstrong>: Monitor webhook performance and errors\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2>Troubleshooting\u003C\u002Fh2>\n\u003Ch3>Common issues\u003C\u002Fh3>\n\u003Cp>\u003Cstrong>"Webhook timeout"\u003C\u002Fstrong>\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Ensure your endpoint responds within 30 seconds\u003C\u002Fli>\n\u003Cli>Move heavy processing to background jobs\u003C\u002Fli>\n\u003Cli>Check server performance and resources\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>\u003Cstrong>"Connection refused"\u003C\u002Fstrong>\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Verify your webhook URL is accessible from the internet\u003C\u002Fli>\n\u003Cli>Check firewall settings\u003C\u002Fli>\n\u003Cli>Ensure your server is running\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>\u003Cstrong>"Invalid signature"\u003C\u002Fstrong>\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Verify you're using the correct webhook secret\u003C\u002Fli>\n\u003Cli>Check signature calculation implementation\u003C\u002Fli>\n\u003Cli>Ensure payload is not modified before verification\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch3>Replay and retry\u003C\u002Fh3>\n\u003Cblockquote>\n\u003Cp>\u003Cstrong>Replay and Retry:\u003C\u002Fstrong> Paid plans can replay successful webhook deliveries or retry failed ones directly from the \u003Cstrong>Logs\u003C\u002Fstrong> view in the dashboard. This is useful for debugging without resending the original email.\u003C\u002Fp>\n\u003C\u002Fblockquote>\n\u003Ch3>Debugging tools\u003C\u002Fh3>\n\u003Cul>\n\u003Cli>\u003Cstrong>Webhook logs\u003C\u002Fstrong>: Check delivery logs in your dashboard\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Request inspection\u003C\u002Fstrong>: Use tools like ngrok for local testing\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Network monitoring\u003C\u002Fstrong>: Monitor network connectivity and latency\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2>Advanced configuration\u003C\u002Fh2>\n\u003Ch3>Multiple webhooks\u003C\u002Fh3>\n\u003Cp>You can configure multiple webhooks for different purposes:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Primary webhook for main processing\u003C\u002Fli>\n\u003Cli>Backup webhook for redundancy\u003C\u002Fli>\n\u003Cli>Specialized webhooks for specific email types\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch3>Conditional webhooks (roadmap)\u003C\u002Fh3>\n\u003Cp>Configure webhooks to trigger based on conditions:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Sender email address\u003C\u002Fli>\n\u003Cli>Subject line patterns\u003C\u002Fli>\n\u003Cli>Attachment presence\u003C\u002Fli>\n\u003Cli>Email size\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2>Next steps\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>\u003Ca href=\"\u002Fhelp\u002Falias-options-explained\u002F\">Set up email aliases\u003C\u002Fa> to route emails to webhooks\u003C\u002Fli>\n\u003Cli>\u003Ca href=\"\u002Fhelp\u002Fwebhook-configuration\u002F\">Learn about email processing\u003C\u002Fa> options\u003C\u002Fli>\n\u003Cli>Configure attachment handling (contact support for advanced options)\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2>Need help?\u003C\u002Fh2>\n\u003Cp>Having webhook issues?\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Contact our support team at \u003Ca href=\"mailto:support@emailconnect.eu\">support@emailconnect.eu\u003C\u002Fa>\u003C\u002Fli>\n\u003Cli>Review webhook logs in your dashboard\u003C\u002Fli>\n\u003Cli>Contact support with webhook URL and error details\u003C\u002Fli>\n\u003C\u002Ful>\n",1781207681451]