Create a Webhook
Configure an HTTPS webhook endpoint in your Emalc account to receive instant HTTP push notifications for email delivery telemetry, audience changes, domain DNS updates, and suppressions.
Step-by-Step Provisioning Guide#
1. Open Webhook Settings#
In your Emalc dashboard, navigate to Settings -> Webhooks and click Add Webhook Endpoint.
2. Enter Endpoint Details#
- Endpoint Name: Provide a descriptive label (e.g.,
Production Order Service,Stripe Billing Sync). - Endpoint URL: Enter your public HTTPS URL (e.g.,
https://api.yourdomain.com/webhooks/emalc).
⚠️ HTTPS Requirement: Production webhook URLs must use the
https://protocol served with a valid TLS certificate.
3. Select Event Subscriptions#
Choose which events trigger HTTP dispatches to your endpoint. You can select All Events or pick specific event categories:
| Category | Event Name | Description |
|---|---|---|
email.sent | Triggered when an email is accepted and queued for transmission. | |
email.delivered | Triggered when recipient mail server acknowledges delivery. | |
email.soft_bounce | Triggered when temporary delivery issues occur. | |
email.bounced | Triggered on permanent hard bounce (SMTP 550 unknown user). | |
email.complained | Triggered when recipient flags email as spam/abuse complaint. | |
email.opened | Triggered when recipient renders tracking pixel. | |
email.clicked | Triggered when recipient clicks a link in email body. | |
email.unsubscribed | Triggered when recipient clicks unsubscribe link. | |
email.suppressed | Triggered when send attempt is blocked by suppression list. | |
email.failed | Triggered on delivery worker or SES gateway failure. | |
| Contacts | contact.created | Triggered when a new contact is added to audience. |
contact.updated | Triggered when contact metadata is modified. | |
contact.deleted | Triggered when a contact is removed. | |
| Domains | domain.created | Triggered when a sender domain is added. |
domain.updated | Triggered when DNS verification status changes. | |
domain.deleted | Triggered when a domain is removed. | |
| Suppressions | suppression.added | Triggered when address is added to suppression list. |
suppression.removed | Triggered when address is unblocked from suppressions. |
4. Secure Your Secret Key#
When your endpoint is created, Emalc generates a unique cryptographic Secret Key starting with whsec_ (e.g., whsec_9f83a021b47e...).
- Store this secret key safely in your server environment variables (
EMALC_WEBHOOK_SECRET). - Use this secret key to perform HMAC-SHA256 Signature Verification on incoming requests.
5. Send a Test Ping#
Click Test Endpoint in the dashboard to dispatch a sample ping payload to your URL. Verify that your server returns an HTTP 200 OK status and confirms signature computation.