Webhooks
Webhooks
MachFive POSTs events to an HTTPS endpoint you choose. Owners and admins add webhooks, and only when sending is on.
Add a webhook
- Settings → Integrations → Webhooks → Add Webhook.
- Paste your HTTPS endpoint.
- Choose an event type.
- Campaign: All Campaigns. List: All Lists. That one webhook covers every campaign in the workspace, including campaigns you create later. A webhook saved on one campaign only receives that campaign. Every new campaign then needs its own webhook, or its events will not reach you.
- Save. Copy the signing secret. It starts with
whsec_. Open it again any time from that webhook's Signing secret menu.
Event types
| Event | In Settings |
|---|---|
email.sent | Email sent |
email.bounced | Email bounced |
email.replied | Email replied |
lead.created | Lead created |
lead.status.changed | Lead status changed |
lead.interested | Lead status changed to Interested |
lead.meeting | Lead status changed to Meeting |
lead.won | Lead status changed to Won |
lead.not_interested | Lead status changed to Not interested |
lead.wrong_person | Lead status changed to Wrong person |
lead.ooo | Lead status changed to Out of office |
lead.unsubscribed | Lead unsubscribed |
email.replied is the event a reply bot listens for. Its data fields are in Replies.
Envelope
Every delivery is JSON with the same outer fields. data depends on the event type.
| Field | Description |
|---|---|
id | Delivery id. msg_ plus 32 hex characters. The same value as the webhook-id header. |
type | Event type, such as email.replied. |
created_at | When MachFive queued the delivery (ISO 8601). |
workspace_id | Workspace the event belongs to. |
data | Event payload. |
Headers
| Header | Value |
|---|---|
webhook-id | Same as the JSON id. |
webhook-timestamp | Unix time, in seconds, when this attempt was sent. |
webhook-signature | One or more space-separated signatures. The current scheme is v1, plus base64. |
Check the signature
The signed content is the raw request body, not a re-parsed object. Compute HMAC-SHA256 over:
{webhook-id}.{webhook-timestamp}.{raw body}The HMAC key is the signing secret with the whsec_ prefix removed, then base64-decoded. Reject a webhook-timestamp more than 5 minutes from now. webhook-signature can hold more than one space-separated signature. Accept the delivery when any v1, value matches. Compare with crypto.timingSafeEqual.
const crypto = require('crypto');
function verifyMachFiveWebhook(secret, headers, rawBody) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const header = headers['webhook-signature'] || '';
const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (!Number.isFinite(age) || age > 5 * 60) return false;
const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
const expected =
'v1,' +
crypto.createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest('base64');
const expectedBuf = Buffer.from(expected);
return header.split(' ').some((part) => {
const presented = part.trim();
if (!presented.startsWith('v1,')) return false;
const got = Buffer.from(presented);
if (got.length !== expectedBuf.length) return false;
return crypto.timingSafeEqual(expectedBuf, got);
});
}Reject the request when the check fails. Use the raw body bytes. JSON.stringify of a parsed object will not match, because key order and spacing differ.
Delivery and retries
MachFive waits up to 10 seconds for your response. 2xx is success. A timeout, a network error, a redirect, or any other status is a failure.
A failed delivery is tried up to 8 times. After a failure the next try waits about 30 seconds, then 2 minutes, 10 minutes, 30 minutes, 2 hours, 6 hours, and 12 hours. Each wait varies by about 20%. The same JSON body and the same webhook-id are sent again. webhook-timestamp and webhook-signature are new on each attempt. After the 8th failure that delivery stops. Eight failures on the endpoint turn the webhook off.
Good practice
Return 2xx as soon as you have stored the body. Do the rest of the work after you respond. A slow call will hit the 10 second limit and MachFive will retry. Before you act on a delivery, skip a webhook-id you have already handled. A retry of that delivery would otherwise run your handler twice.