[{"data":1,"prerenderedAt":12},["ShallowReactive",2],{"$fCVDJa43mnhU8gM5FIxiVVPtGsmWL4IXwiBzYfUfd7eA":3},{"title":4,"slug":5,"excerpt":6,"category":7,"order":8,"screens":9,"html":11},"Custom webhook headers","custom-webhook-headers","Configure custom HTTP headers for authentication, routing, and testing webhooks","configuration",5,[10],"webhooks","\u003Cp>Custom headers in EmailConnect webhooks provide powerful capabilities for authentication, routing, and testing. Here's everything you need to know about configuring and using them effectively.\u003C\u002Fp>\n\u003Ch2>What are custom headers?\u003C\u002Fh2>\n\u003Cp>Custom headers are additional HTTP headers sent with every webhook request. They can be used for:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Authentication tokens\u003C\u002Fli>\n\u003Cli>API versioning\u003C\u002Fli>\n\u003Cli>Request routing\u003C\u002Fli>\n\u003Cli>Testing scenarios\u003C\u002Fli>\n\u003Cli>Metadata passing\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2>Adding custom headers\u003C\u002Fh2>\n\u003Ch3>In the webhook form\u003C\u002Fh3>\n\u003Col>\n\u003Cli>Navigate to your alias\u003C\u002Fli>\n\u003Cli>Click "Add webhook" or edit existing\u003C\u002Fli>\n\u003Cli>Find the "Custom headers" section\u003C\u002Fli>\n\u003Cli>Click "Add header"\u003C\u002Fli>\n\u003Cli>Enter header name and value\u003C\u002Fli>\n\u003Cli>Save the webhook\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Ch3>Header format\u003C\u002Fh3>\n\u003Cp>Headers follow standard HTTP conventions:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Name\u003C\u002Fstrong>: Case-insensitive, but typically formatted as \u003Ccode>Header-Name\u003C\u002Fcode>\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Value\u003C\u002Fstrong>: Any string value, including tokens, JSON, etc.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2>Common use cases\u003C\u002Fh2>\n\u003Ch3>Authentication\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: Authorization\nValue: Bearer your-api-token-here\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cpre>\u003Ccode>Header: X-API-Key\nValue: sk_live_abcd1234efgh5678\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3>Webhook signatures\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: X-Webhook-Secret\nValue: shared-secret-for-hmac-verification\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3>Content type override\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: Content-Type\nValue: application\u002Fx-www-form-urlencoded\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3>Custom routing\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: X-Environment\nValue: production\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cpre>\u003Ccode>Header: X-Tenant-ID\nValue: customer-123\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2>Testing with WebhookTest\u003C\u002Fh2>\n\u003Cp>WebhookTest offers special headers for testing scenarios without deploying code:\u003C\u002Fp>\n\u003Ch3>Simulating HTTP errors\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: X-Mock-Status\nValue: 500\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Returns a 500 Internal Server Error, perfect for testing retry logic.\u003C\u002Fp>\n\u003Ch3>Adding response delays\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: X-Mock-Delay\nValue: 3000\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Delays response by 3 seconds (3000ms) to test timeout handling.\u003C\u002Fp>\n\u003Ch3>Custom response bodies\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: X-Mock-Response\nValue: {"status": "queued", "id": 12345}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Returns custom JSON response for testing parsers.\u003C\u002Fp>\n\u003Ch3>Different content types\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: X-Mock-Content-Type\nValue: text\u002Fplain\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Tests how your system handles non-JSON responses.\u003C\u002Fp>\n\u003Ch2>Real-world examples\u003C\u002Fh2>\n\u003Ch3>Connecting to Slack\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: Authorization\nValue: Bearer xoxb-your-slack-token\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3>Zapier webhook\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: X-Hook-Secret\nValue: your-zapier-hook-secret\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3>Custom CRM integration\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: X-Company-ID\nValue: COMP-12345\nHeader: X-API-Version\nValue: v2\nHeader: X-Source\nValue: email-automation\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3>Multi-tenant SaaS\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: X-Tenant\nValue: acme-corp\nHeader: X-Workspace\nValue: engineering\nHeader: X-Priority\nValue: high\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2>Security best practices\u003C\u002Fh2>\n\u003Ch3>Don't expose sensitive data\u003C\u002Fh3>\n\u003Cul>\n\u003Cli>Use environment-specific values\u003C\u002Fli>\n\u003Cli>Rotate tokens regularly\u003C\u002Fli>\n\u003Cli>Never commit webhook configurations to version control\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch3>Use HTTPS endpoints\u003C\u002Fh3>\n\u003Cul>\n\u003Cli>Always use HTTPS URLs for webhooks\u003C\u002Fli>\n\u003Cli>Headers are encrypted in transit with HTTPS\u003C\u002Fli>\n\u003Cli>Avoid HTTP endpoints for sensitive data\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch3>Use webhook signing\u003C\u002Fh3>\n\u003Cp>Instead of static authentication, enable \u003Ca href=\"\u002Fhelp\u002Fwebhook-signing\u002F\">webhook signing\u003C\u002Fa> which follows the Standard Webhooks convention:\u003C\u002Fp>\n\u003Col>\n\u003Cli>Each request is signed with HMAC-SHA256\u003C\u002Fli>\n\u003Cli>Timestamp included for replay protection\u003C\u002Fli>\n\u003Cli>Verify using any Standard Webhooks-compatible library\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Ch2>Advanced patterns\u003C\u002Fh2>\n\u003Ch3>Environment-based headers\u003C\u002Fh3>\n\u003Cp>Create separate webhooks for different environments:\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Development webhook:\u003C\u002Fstrong>\u003C\u002Fp>\n\u003Cpre>\u003Ccode>URL: https:\u002F\u002Fdev.api.example.com\u002Fwebhook\nHeader: X-Environment\nValue: development\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>\u003Cstrong>Production webhook:\u003C\u002Fstrong>\u003C\u002Fp>\n\u003Cpre>\u003Ccode>URL: https:\u002F\u002Fapi.example.com\u002Fwebhook\nHeader: X-Environment\nValue: production\nHeader: Authorization\nValue: Bearer prod-token-here\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3>Feature flags\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: X-Feature-Flag\nValue: new-parser-enabled\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Your endpoint can use this to test new features gradually.\u003C\u002Fp>\n\u003Ch3>Request tracing\u003C\u002Fh3>\n\u003Cpre>\u003Ccode>Header: X-Request-ID\nValue: webhook-{{timestamp}}-{{random}}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Note: Variable substitution coming in future updates.\u003C\u002Fp>\n\u003Ch2>Troubleshooting\u003C\u002Fh2>\n\u003Ch3>Headers not appearing\u003C\u002Fh3>\n\u003Col>\n\u003Cli>Check header name doesn't conflict with reserved headers\u003C\u002Fli>\n\u003Cli>Ensure no typos in header names\u003C\u002Fli>\n\u003Cli>Verify webhook is saved after adding headers\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Ch3>Authentication failing\u003C\u002Fh3>\n\u003Col>\n\u003Cli>Verify token\u002Fkey is correct\u003C\u002Fli>\n\u003Cli>Check if token has expired\u003C\u002Fli>\n\u003Cli>Ensure header name matches API expectations\u003C\u002Fli>\n\u003Cli>Test with curl to isolate issues\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Ch3>Testing headers locally\u003C\u002Fh3>\n\u003Cp>Use curl to simulate EmailConnect webhooks:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-bash\">curl -X POST https:\u002F\u002Fyour-endpoint.com\u002Fwebhook \\\n  -H "Content-Type: application\u002Fjson" \\\n  -H "X-API-Key: your-key" \\\n  -H "X-Custom-Header: test-value" \\\n  -d '{"test": "payload"}'\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch2>Tips and tricks\u003C\u002Fh2>\n\u003Ch3>Header templates\u003C\u002Fh3>\n\u003Cp>Save common header combinations:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Production auth headers\u003C\u002Fli>\n\u003Cli>Development\u002Ftest headers\u003C\u002Fli>\n\u003Cli>Integration-specific headers\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch3>Documentation\u003C\u002Fh3>\n\u003Cp>Document your headers:\u003C\u002Fp>\n\u003Cpre>\u003Ccode># Webhook Headers\n- Authorization: Bearer token for API access\n- X-Webhook-Source: Always "emailconnect"\n- X-Customer-ID: Dynamic based on sender domain\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Ch3>Monitoring\u003C\u002Fh3>\n\u003Cp>Log custom headers on receiving end for debugging:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>Track which headers are present\u003C\u002Fli>\n\u003Cli>Monitor for missing headers\u003C\u002Fli>\n\u003Cli>Alert on authentication failures\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Custom headers make your webhooks flexible and secure, enabling seamless integration with any HTTP endpoint.\u003C\u002Fp>\n",1781207681514]