Keep a local copy up to date
Combine webhooks with polling so your copy of Imploy data stays correct.
Webhooks tell you quickly when something changes. They are not a guarantee. Each delivery is attempted once, so a delivery can be missed if your endpoint is down or slow. The reliable pattern is webhooks for speed, plus polling to catch anything missed.
The pattern
Load everything once
Page through the list endpoint (for example GET /clients) and store each record by its Imploy id.
Apply webhook events
On client.created and client.updated, upsert the record from the event data. On a delete event, remove or flag it.
Reconcile on a schedule
Every so often, call the list endpoint with updated_since set to your last checkpoint. This picks up anything a webhook missed.
Handle events safely
- Return fast. Save the event to a queue, answer
200, and process it afterwards. You have 5 seconds. - Ignore repeats. Store the
event_idfor events you've handled and skip duplicates. - Don't rely on order. Compare
occurred_at, or fetch the record again withGET /clients/{id}when in doubt. - Batches. A delivery can carry up to 50 events. When
eventisbatch, loop overevents. - Truncated fields. Long values may be shortened. Any shortened field is listed in
truncated_fields, so fetch the record if you need the full value. - Test events. Skip anything with
is_testset totrue.
function handle(body) {
const events = body.event === "batch" ? body.events : [body];
for (const e of events) {
if (e.is_test) continue;
if (alreadySeen(e.event_id)) continue;
switch (e.event) {
case "client.created":
case "client.updated":
upsertClient(e.data, e.changed_fields);
break;
case "staff.updated":
upsertStaff(e.data);
break;
}
markSeen(e.event_id);
}
}
Archiving
Clients and staff are archived, not removed. Archiving sends an updated event with the status changed, so check status in your handler.