In order to handle webhook deliveries, you need to set up a server that can receive and process HTTP POST requests.
Create your handler
Set up an HTTP or HTTPS endpoint function that can accept webhook requests with a POST method. If you’re still developing your endpoint function on your local machine, you can use tools like ngrok to expose your local server to the internet so that you can use this public URL as the target URL in the webhook configuration.
Set up your endpoint function so that it:
- Handles POST requests with a JSON payload consisting of an event object.
- Quickly returns a successful status code (2xx) prior to any complex logic that might cause a timeout. For example, you must return a 200 response before synchronizing data with an external system.
Secure your handler
Once your server is configured to receive payloads, it will listen for any delivery that’s sent to the endpoint you configured. To ensure that your server only processes webhook deliveries that were sent by folk and to ensure that the delivery was not tampered with, you should validate the webhook signature before processing the delivery further. This will help you avoid spending server time to process deliveries that are not from folk and will help avoid man-in-the-middle attacks.
Every time you create a new webhook, folk will generate a new webhook secret. This secret is used to verify the webhook signature, and should be stored securely.
The webhook secret is only visible once at webhook creation. If you lose it,
you will need to create a new webhook.
Remember to provide the raw body for the verification. If you are using a
framework, make sure it doesn’t manipulate the raw body. Any manipulation to
the raw body causes the verification to fail.
Event delivery behaviors
This section helps you understand different behaviours to expect regarding how folk sends events to your webhook endpoint.
Automatic retries
folk attempts to deliver events to your handler for up to one day, using the following backoff strategy:
| Delay | Time since start |
|---|
| Immediately | 00:00:00 |
| 5 seconds | 00:00:05 |
| 5 minutes | 00:05:05 |
| 30 minutes | 00:35:05 |
| 2 hours | 02:35:05 |
| 5 hours | 07:35:05 |
| 10 hours | 17:35:05 |
| 14 hours | 31:35:05 |
| 20 hours | 51:35:05 |
| 24 hours | 75:35:05 |
A webhook delivery is considered successful if it was responded to with a 2xx status code (status codes 200-299), and it is considered a failure in any other scenario.
If an event delivery uses all of the available retries, or if a webhook is experiencing a high error rate, folk will deactivate the webhook. You will be notified via email when this happens.
After a webhook is deactivated, you will no longer receive any events for that webhook. You will need to re-activate the webhook to start receiving events again.
If the webhook handler responds with a 410 Gone status code, the endpoint
will be considered inactive and the webhook will be deactivated immediately,
without any retries.
Event ordering
folk doesn’t guarantee the delivery of events in the order that they’re generated. For example, creating a deal might generate the following events:
object.created ( the deal is created )person.updated ( if the deal is assigned to at least one person )company.updated ( if the deal is assigned to at least one company )
Make sure that your event handler isn’t dependent on receiving events in a specific order. Be prepared to manage their delivery appropriately. You can also use the API to retrieve any missing information.
Best practices
Handle duplicated events
Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts by logging the event IDs you’ve processed, and then not processing already-logged events.
We suggest storing the processed event IDs for at least 48 hours.
Only listen to event types your integration requires
Configure your webhook endpoints to receive only the types of events required by your integration. Listening for extra events (or all events) puts undue strain on your server and we don’t recommend it.
You can change the events that a webhook endpoint receives in the workspace settings or with the API.
Handle events asynchronously
Configure your handler to process incoming events with an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously. Any large spike in webhook deliveries (for example, during a data import) might overwhelm your endpoint hosts.
Asynchronous queues allow you to process the concurrent events at a rate your system can support.
Your endpoint must reply within 20 seconds, otherwise the delivery will be considered failed and folk will retry the delivery.
Exempt webhook route from CSRF protection
If you’re using Rails, Django, Laravel, or another web framework, your site might automatically check that every POST request contains a CSRF token. This is an important security feature that helps protect you and your users from cross-site request forgery attempts. However, this security measure might also prevent your site from processing legitimate events. If so, you might need to exempt the webhooks route from CSRF protection. 
