Outgoing webhooks in Naffes CRM: signed events to your endpoint

When to use outgoing webhooks

Use them when another system must know the moment a record changes in Naffes, instead of polling. Typical cases: push new contacts into accounting, update a data warehouse whenever a deal is edited, or remove a record from your marketing tool when it is deleted in Naffes.

They differ from the Make and n8n connectors in the Marketplace in three ways: nine events instead of one, a signature on every request, and automatic retries. That makes them the right choice for any integration your operations depend on.

Creating a webhook

1. 1

   Open the Webhooks screen

   As a workspace admin, go to Settings > Integrations > Apps & APIs > Webhooks.

2. 2

   Add a webhook

   Click New webhook, give it a descriptive name and paste a public HTTPS endpoint URL on your server.

3. 3

   Choose the event

   Type one event name, such as deal.created or contact.updated, a pattern such as deal.* for all deal events, or * for everything, then create it.

4. 4

   Get the signing secret

   The screen shows only the last 4 characters of the secret. To get it in full, create the subscription with POST /api/webhook-subscriptions, or rotate an existing one with POST /api/webhook-subscriptions/{id}/rotate-secret; the full secret appears once, in that response only.

5. 5

   Watch deliveries

   Each webhook card shows its success rate, deliveries in the last 24 hours and the last delivery time, with pause and resume controls.

Events, payload and headers

The JSON body carries event, delivered_at, delivery_id, data with the record's attributes (plus the changed fields on updates), and actor, which says whether a user or the system made the change.

• X-Naffes-Event: the event name.
• X-Naffes-Delivery-Id: the delivery ID, unchanged across retries, so use it to deduplicate.
• X-Naffes-Webhook-Id: the subscription ID.
• X-Naffes-Signature: in the form t=timestamp,v1=signature.

The signature is an HMAC-SHA256, keyed with the subscription secret, of the timestamp, a dot, and the raw request body. Compute it over the bytes exactly as received, not over parsed and re-encoded JSON: Arabic text arrives as \uXXXX escapes, and any re-encoding changes the signature. In Node.js:

const crypto = require('crypto');

function verifyNaffes(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Retries and auto-pause

Any non-success response counts as a failure. Naffes makes up to 7 attempts in total: the first, then after 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 24 hours. Every delivery is recorded. If at least half of the recent deliveries end up dead after using all their attempts, and there are 10 or more of them, the subscription pauses itself; fix the endpoint and resume it from the list.

Limits

• The full secret is not shown in the UI. Signature checks require fetching it from the API at creation or rotation.
• One event per webhook in the UI. The API accepts a list of events on one subscription.
• Delivery log is API-only: GET /api/webhook-subscriptions/{id}/deliveries.
• Only three record types. No events for tasks, meetings, notes, tickets, invoices or messages.
• No dedicated stage-change event. Watch the changed fields on deal.updated, or use the deal.stage_changed feed the Marketplace sends to Make and n8n.
• Public endpoints only. Private and internal addresses are refused.

Questions