POST request to it with the details.
Events
A webhook listens to both events by default. You can pick just one when you register it.
From the dashboard
You don’t need the API to manage webhooks. Open your project, go to Settings, then the Integrations tab, and scroll down to Webhooks. From there you can:- Add a webhook: paste your URL and pick which events it should get.
- See how each one is doing: when the last delivery went through, or why the last one failed.
- Send test to check your server answers.
- Pause a webhook and Resume it later.
- Delete it.
Register a webhook
You’ll need an API token (see Authentication) for a user who can edit the project: the owner, an administrator or an editor. Send aPOST to your project’s webhooks endpoint with your API token:
- It has to be
https, and reachable from the internet. Internal and private addresses are rejected. - We don’t follow redirects, so point it at the final address.
- Each project can have up to 10 webhooks.
What we send
Every delivery is aPOST with a JSON body like this:
data depends on the fields of your form, so it can have more or fewer fields than this example.
data.id is the lead’s id in Planpoint. It’s missing if your account is set up not to store leads.
And these headers:
Answer with any
2xx status within 5 seconds to let us know you got it. Anything else, or no answer in time, counts as a failure and we’ll retry.
The same event can occasionally reach you more than once (for example, if your server got it but answered too late). Use
id to ignore repeats.Verify the signature
Anyone could send a request to your URL, so check the signature before trusting it. TheX-Planpoint-Signature header has two parts:
t: when we sent it, in Unix seconds.v1: an HMAC-SHA256 of"<t>.<raw body>", using your webhook secret as the key, in hex.
Retries
If a delivery fails, we try again with growing gaps between attempts:
That’s one first attempt plus 5 retries, over about 15 hours. Every retry carries the same body, with the same
id. If the last one also fails, we stop trying for that event.
Automatic pause
If a webhook fails 20 times in a row, we pause it so we don’t keep calling a server that’s down. While it’s paused, no events are sent to it. Once your server is back, turn it on again (see below): that also resets its failure count. Retries that were still pending when it got paused are dropped.Manage your webhooks
All of these use the sameAuthorization: Bearer YOUR_API_TOKEN header.
List them
lastStatus, lastError, lastDeliveryAt, failureCount). lastError stays there after a later delivery works, so go by failureCount to tell whether a webhook is healthy. The secret is never shown again, only its last 4 characters in secretHint, so you can tell them apart.
Send a test
webhook.test event to your URL right away and tell you how it went:
webhook is the webhook as it is right after the test, with its delivery status updated. Like everywhere else, it never includes the secret.
It’s the quickest way to check your URL and your signature code before real leads come in. Test events aren’t retried. A failed test does count toward the automatic pause, and a successful one resets the count.
Pause or turn it back on
{ "active": true } to turn it back on.
The response is { "webhook": { ... } }, with the webhook in the same shape as in the list.