Create a CRM activity after a call

This is the smallest complete Talki integration: every completed call becomes an activity attached to a CRM person.

1. Subscribe

Create a webhook endpoint for call.ended. Save its signing secret once, then send a ping from the dashboard to prove the public HTTPS route is reachable.

2. Accept safely

On every request:

1. Capture the raw request body.
2. Verify the HMAC signature.
3. Insert the envelope id into a table with a unique constraint.
4. Return 204 as soon as the event is durably queued.

If the event ID already exists, return 204 without running the job again.

3. Resolve the person

Read the Call from data.object. Prefer caller.contact_id once you have mapped it. For the first encounter, match caller.phone_number in E.164 form. A withheld number is null; route that call to an unmatched activity instead of inventing an identity.

caller.display_name only contains a name curated or imported by the account owner. It can legitimately be null.

4. Upsert the activity

Use the Talki Call id as an external unique key in the CRM. Store the summary, timing, caller mapping, and any appointment_ids your CRM needs. Upsert rather than insert so manual redelivery repairs the existing activity.

New code should ignore the deprecated flat fields beside data.object.

5. Recover missed calls

Persist the greatest Call created_at successfully applied. On startup and on a schedule:

1. Subtract one minute from the watermark.
2. Request /v1/calls?created_after=…&limit=100.
3. Upsert every returned Call by ID.
4. Follow next_cursor until has_more is false.
5. Advance the watermark only after the full sweep succeeds.

The overlap intentionally returns some calls twice. Idempotent upserts make that cheap; omitting the overlap can silently miss a concurrently committed call.