Glossary term
Webhook
A webhook is an HTTP request one system sends to a URL you choose the moment something happens, such as a deal being created or a contact updated, so your other system learns about the change immediately instead of asking every few minutes.
What is a webhook?
A webhook is an integration pattern in which the source system sends an HTTP request, usually a POST carrying JSON, to a URL owned by the receiving system at the moment an event it subscribed to occurs. Instead of an accounting system asking the CRM every five minutes whether anything is new, which is called polling, the CRM tells it the instant a customer is created or a deal changes. Every webhook has four parts: the event that fires it, the endpoint that receives it, the payload describing what changed, and a signature proving the request really came from the source and was not tampered with on the way. Because networks and servers fail from time to time, a good sender retries failed deliveries and a good receiver copes with getting the same event more than once without repeating its effect.
| Question | Webhook | Polling |
|---|---|---|
| Who starts the request | The source, when the event happens | The receiver, on a fixed interval |
| How fast changes arrive | Near real time | Depends on the interval |
| Load on both systems | One request per event | Repeated requests even when nothing changed |
| What the receiver needs | A public endpoint that verifies signatures | API credentials |
Receiving webhooks safely
- Verify the signature. The sender computes an HMAC of the payload with a shared secret, a mechanism defined in RFC 2104; you recompute it with the same secret, compare, and reject anything that does not match.
- Check the timestamp and reject stale requests, so a captured request cannot be replayed later.
- Answer quickly with a success status and do the work in the background, so the sender does not treat a slow response as a failure and retry.
- Make processing idempotent: store each delivery's ID and ignore any you have already handled.
- Monitor failures. An endpoint that stops responding can get its subscription paused or leave events piling up.
Illustrative example: an events company wants each deal update in its CRM to refresh the matching booking in its operations system. It subscribes to deal updates and reads the changed fields in each payload. One evening its server is down for an hour; the sender retries later, and one update arrives twice. Because the receiver stores delivery IDs, the second copy is ignored and no booking is changed twice, the same principle that data deduplication applies inside the CRM.
In Naffes CRM
Workspace admins in Naffes CRM register outgoing webhooks under Settings > Integrations > Apps & APIs > Webhooks, entering a name, an HTTPS endpoint and an event name.
| Area | Details |
|---|---|
| Events | 9 events: contact, company and deal, each created, updated or deleted. The screen creates a subscription for one event typed by name, such as deal.created; patterns such as deal.* or * for all events go through the API |
| Payload | The record's attributes, plus the changed fields on updates |
| Signature | HMAC-SHA256 in the X-Naffes-Signature header (timestamp and signature), with X-Naffes-Event, X-Naffes-Delivery-Id and X-Naffes-Webhook-Id headers |
| Retries | Up to 7 attempts in total, retried after 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 24 hours |
| Auto-pause | A subscription pauses itself when at least half of its last 10 or more deliveries have failed for good, and can be resumed from the screen once the endpoint is fixed |
| Monitoring | Each webhook card shows its success rate and 24-hour delivery count |
Separately, Make, n8n and a Custom Webhook URL set up in the Marketplace each receive a deal.stage_changed event whenever a deal changes stage, but those deliveries are unsigned and not retried. And the 'HTTP request' step in a workflow calls any public URL and passes the response status and body to later steps. Setup steps and a signature-verification example are on the Webhooks integration page.
Plan and screen limits: webhook subscriptions need the Pro plan or above. The screen shows only the last 4 characters of the signing secret, so verifying signatures currently requires fetching the full secret from the API at creation or rotation. The screen cannot subscribe one webhook to several events or show the delivery log. There are no events for tasks, tickets, invoices or messages, and no inbound webhook that accepts requests from outside systems.
Questions
Questions 2
What is the difference between a webhook and an API?
An API waits for your system to ask: your side starts the request to read or change data. A webhook starts from the source and tells you about a change as it happens. Real integrations usually use both: the webhook signals, and the API fetches details or makes the change.
Why did I receive the same event twice?
Because the sender retries when it does not get a timely success response, even if the first request actually arrived. That is why every Naffes delivery carries an ID in the X-Naffes-Delivery-Id header; use it to skip deliveries you have already processed.