Call webhooks for phone summaries

A woman at a desk writing notes while talking on a phone
Photo by Yan Krukau on Pexels. A person writing notes during a phone call. The notes are not a RingKit summary.

Call webhooks are how a phone summary leaves RingKit without you polling. You register a URL. When a call ends, RingKit POSTs JSON to it. One of the three events carries the summary of the conversation. The other two do not. If you store the wrong one, you will file a balance warning as a customer message, or you will miss the message and keep only a billing row.

The events, the signing header, and the retry rule are in the webhook section of the docs. What follows is which event to store, how to check the signature against the raw body, and what a retry means for your database. Branch on type before you read data. The secret that signs the POST comes back once, and a slow answer is sent again. The setup that creates the business is AI receptionist API. This page starts after that business exists.

Three events, one summary

Create the webhook with POST /v1/businesses/:id/webhooks and a body of { url, events }. The response is { id, secret }. The secret is shown once. Store it before you do anything else. You cannot read it back from GET. If you lose it, create another webhook and stop trusting the old URL.

EventWhat data holdsWhen it is sent
call.completed{ call, transcript }The call has ended and been billed. The summary is on the call when it is ready.
message.taken{ callId, message, summary }The receptionist took a message.
balance.low{ balanceCents }A call took the wallet below $2.

Subscribe to the events you will actually handle. A URL that returns 200 for everything, and then ignores two of the three types, is a fine design. A URL that assumes every POST is a message is not.

call.completed is the record of the call: who called, what they needed, the next step, the transcript, and the bill. The summary includes intent, outcome, the caller name, a short write-up, any message, and whether someone should follow up. message.taken is the narrower event. It fires when a message was taken, and it repeats the message and a summary so you do not have to dig them out of the transcript. Use message.taken to open a task. Use call.completed as the archive. A call that transferred and took no message still completes. It will not send message.taken. If you only listen for messages, you will never see that call.

What a message looks like

The docs include a sample, not a real customer. The shape is the part to copy. A message.taken body is { type, createdAt, data }. Inside data are callId, message, and summary. The message has callerName, callbackNumber, message, and urgency. The summary has intent, outcome, callerName, summary, and followUpNeeded.

Store callId as the id of the row. Store the callback number the caller gave, which may differ from the number that placed the call. Store urgency as the word the receptionist picked from the brief, not as a promise that someone is already driving. followUpNeeded means the summary says a person should do something. It does not dial anyone. RingKit does not text the caller, and this POST is not a text message. It is your server receiving JSON.

call.completed carries the same call and transcript as GET /v1/businesses/:id/calls/:callId. If the webhook and the GET disagree because you re-fetched later, keep the GET for the archive and treat the webhook as the notice that it was time to look. The transcript is how the summary was made. Calls are recorded for that summary, and a consent notice plays on every call. The receptionist always says it is an AI.

Check the signature on the raw body

Every delivery has the header X-RingKit-Signature: t=<unix seconds>,v1=<hex>. The hex is HMAC-SHA256 of the timestamp, a period, and the raw body, keyed with the webhook secret. RFC 2104 is the note that defines HMAC: message authentication with a cryptographic hash and a shared secret. The RingKit header is that construction, with SHA-256 as the hash. The RFC's own examples name earlier hashes. The construction is what you are implementing, not a claim that the RFC printed this header.

Reject a timestamp more than five minutes from now. The signature is made at send time, so an old t is not a delivery you should act on. Compute the HMAC over the exact bytes you received. If you parse the JSON and stringify it again, the bytes change and a valid delivery fails. Compare the digests in constant time, and only after checking they are the same length. A plain string compare can leak how much of the signature matched.

The docs give a Node function, verifyRingkit(rawBody, header, secret), that splits the header on commas, checks the five-minute window, and uses crypto.timingSafeEqual. Use that, or the same steps outside Node. Express needs the raw body, which means express.raw on this route, not a JSON parser that has already replaced req.body with an object. Return 204 when the check passes. Return 400 for a bad signature so the retry rule treats it as permanent.

Answer within five seconds, and expect a duplicate

Respond with any 2xx within 5 seconds. Timeouts and other responses are retried with exponential backoff, up to 10 attempts, about a day and a half. A 4xx other than 408 or 429 is not retried. 408 and 429 are, because they mean "not now" rather than "never."

That retry rule means your handler must be safe to run twice. A second POST of the same call.completed is not a second call. Key the row on callId and the event type, and ignore a duplicate. Do the slow work after you have answered. A handler that writes to three other systems and then returns 200 will cross five seconds, and RingKit will send the call again. Return 204 first, or do the work in a queue that dedupes on callId.

balance.low is the event that does not belong in the message inbox. data is { balanceCents }. It fires when a call takes the wallet under $2. A number still costs $1.99 a month, and talk time is $0.20 a minute from that same wallet, so a low balance is a funding problem, not a caller. Top up from the pricing page rules: $10 is the smallest top-up, a person pays the checkout URL, and there is no free trial. Do not open a customer task because the wallet dropped.

What you should not build on this

There is no webhook for "a call is ringing," and there is no webhook that books a calendar. A requested time, if the caller named one, is text inside the summary. There is no CRM event and no SDK that wraps this POST. The MCP tool ringkit_create_webhook registers the same URL and events. The signature check does not change because you used a tool instead of curl. That tool list is MCP phone receptionist.

If your handler cannot verify the signature, do not store the body "for now." An unsigned POST to a public URL is not a summary. It is someone else's JSON wearing the same shape. If two systems both need the event, register two webhooks. Each URL gets its own secret. Do not copy one secret onto the other endpoint, and do not fan out inside the five-second window and hope the second system was up.