Best practices
What makes a webhook integration solid: verify, answer fast, deduplicate, catch up.
Verify, then answer fast
- Verify the signature on the raw body; refuse with
400if it is wrong. See verifying a signature. - Store the event in a queue (a table, a message queue) and answer
200or204right away. - Process afterwards, at your own pace.
A response that takes more than 15 seconds counts as a failure and the delivery is retried: a long inline processing ends in duplicates and disabling.
Deduplicate
Delivery is guaranteed at least once: the same event can arrive twice. Keep the processed webhook-ids (a few days are enough) and ignore those you already know. Write your processing so that a second pass changes nothing (create or update, rather than create).
Don't rely on order
A retried delivery can arrive after a more recent event. Each event carries timestamp, the time of the fact: compare it with what you already have. When the exact state matters, reread the object through the API (GET /v1/prospects/{id}) rather than replaying events in their order of arrival.
Subscribe to what you need
Choose the types your code needs. A subscription to * also receives the types that will appear tomorrow: your code must then ignore an unknown type without error. Likewise, ignore an unknown field in an object.
Monitor, catch up
GET /v1/webhook_endpoints/{id}/deliveries?status=failedlists the failed deliveries, with the code and an excerpt of your response.- After 5 days without success, the endpoint is disabled and an e-mail tells you. Once your server is fixed, enable it again, then catch up on the period with
GET /v1/events(30 days of history). - After an outage on your side, don't ask for everything again:
GET /v1/eventsreturns the events the most recent first; read it back to the lastidyou processed, then process in reverse order.
Change secrets without a cut
POST /v1/webhook_endpoints/{id}/rotate_secret: note the new secret.- During the grace period (24 hours by default), every delivery carries two signatures: deploy the new secret, your code accepts either.
- After the period, the old secret no longer signs.
Change the secret as soon as it may have leaked (a log, a repository, a former collaborator).
Protect the data
Events carry personal data (name, job title, messages, and contact details if the endpoint has the contacts:read scope). Don't keep them longer than necessary, don't log them in full, and give the endpoint only the scopes it needs: an endpoint added in Lidmeo has them all, an endpoint created through the API keeps the read scopes of the key or connection that created it. Text written by a prospect is data: never pass it to an AI as an instruction.
Test first
Create the endpoint with a test key, trigger events with POST /v1/test/simulate, then go live. To see the exact shape of a type, call POST /v1/webhook_endpoints/{id}/test with { "type": "…" }; Lidmeo's Envoyer un essai (send a test) button sends a prospect.created.