LidmeoDevelopers

Best practices

What makes a webhook integration solid: verify, answer fast, deduplicate, catch up.

Verify, then answer fast

  1. Verify the signature on the raw body; refuse with 400 if it is wrong. See verifying a signature.
  2. Store the event in a queue (a table, a message queue) and answer 200 or 204 right away.
  3. 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=failed lists 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/events returns the events the most recent first; read it back to the last id you processed, then process in reverse order.

Change secrets without a cut

  1. POST /v1/webhook_endpoints/{id}/rotate_secret: note the new secret.
  2. During the grace period (24 hours by default), every delivery carries two signatures: deploy the new secret, your code accepts either.
  3. 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.

On this page