Configure the endpoint
In Integrations → Custom Integrations → Configure → Settings:- Set outbound URL to your public HTTPS endpoint.
- Select the events you want under the outbound event selector.
- Click Test webhook to send a
test.ping.
The endpoint must be reachable from the public internet and must not
require your own auth token — Ringee authenticates by signing the body, not by
sending credentials. Disable JWT verification on the route and verify the
signature instead.
Delivery format
Identify the source
Outbound events can include these shareddata fields:
Actor enrichment is best-effort. Ringee still delivers the event if the user or
agent can no longer be resolved, so treat
data.user and data.agent as
optional. data.externalId follows every call-linked event from the same AI
Voice Agent call, including terminal, outcome, callback, meeting and recording
events.
Verify the signature
The signature isHMAC_SHA256(signingSecret, "<timestamp>.<rawBody>"), hex-encoded.
1
Parse the header
Ringee-Signature has the form t=<unixSeconds>,v1=<hexDigest>. Extract both parts.2
Check the timestamp
Confirm
t matches the Ringee-Timestamp header, and reject anything more than 5 minutes old. This blocks replay attacks.3
Recompute and compare
Compute the HMAC over
`${timestamp}.${rawBody}` with your whsec_… secret and compare in constant time.4
Reject failures with 401
A missing header or a bad signature is a
401. Never store or process an unverified event.The Edge Function that receives Ringee webhooks must have
verify_jwt = false. Ringee does not send a Supabase JWT — the HMAC signature is the
authentication.Respond correctly
200 { "received": true } and 204 No Content are both valid acknowledgements.
Idempotency
The sameeventId can arrive more than once — that is by design, not a bug.
Transport retries reuse the exact stored payload and eventId.
Store received events in a table with a UNIQUE constraint on the event id:
eventId before processing. If the insert conflicts, the event is a duplicate: return 200 and do nothing else.
Retries
After the final attempt the delivery is marked
failed and Ringee sends email and device push notifications to the integration owner or organization admins. Alerts are throttled per integration for six hours. Deliveries are also failed immediately if the integration has been disabled or deleted.
The queued delivery worker runs every 5 seconds and claims up to 100 due
deliveries. It sends independent deliveries in parallel, so neither the queue
cadence nor creation time establishes ordering.
Event ordering
Deliveries are independent rows sent in parallel waves — order is not guaranteed. Design for this:call.outcome.updatedcan arrive beforecall.completed. Upsert the activity bycallIdfrom either event.call.outcome.updatedincludesdata.callwhen the telephony row can still be resolved, so it can create or update the activity by itself.recording.readycan arrive seconds or minutes after the call ended.meeting.createdandcall.outcome.updatedboth fire when an outcome ismeeting_booked.- A subscribed AI Voice Agent call can produce
call.completedorcall.failed, thencall.outcome.updated, and later callback, meeting or recording events. Do not wait for a fixed sequence.
Next steps
Event reference
Every outbound payload, field by field
Build an integration
Mapping, loop prevention and a test checklist

