Webhooks

GuidesUpdated November 12, 2026

Webhooks

MachFive POSTs events to an HTTPS endpoint you choose. Owners and admins add webhooks, and only when sending is on.


Add a webhook

  1. Settings → Integrations → Webhooks → Add Webhook.
  2. Paste your HTTPS endpoint.
  3. Choose an event type.
  4. 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.
  5. Save. Copy the signing secret. It starts with whsec_. Open it again any time from that webhook's Signing secret menu.

Event types

EventIn Settings
email.sentEmail sent
email.bouncedEmail bounced
email.repliedEmail replied
lead.createdLead created
lead.status.changedLead status changed
lead.interestedLead status changed to Interested
lead.meetingLead status changed to Meeting
lead.wonLead status changed to Won
lead.not_interestedLead status changed to Not interested
lead.wrong_personLead status changed to Wrong person
lead.oooLead status changed to Out of office
lead.unsubscribedLead 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.

FieldDescription
idDelivery id. msg_ plus 32 hex characters. The same value as the webhook-id header.
typeEvent type, such as email.replied.
created_atWhen MachFive queued the delivery (ISO 8601).
workspace_idWorkspace the event belongs to.
dataEvent payload.

Headers

HeaderValue
webhook-idSame as the JSON id.
webhook-timestampUnix time, in seconds, when this attempt was sent.
webhook-signatureOne 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.