Skip to main content
WEBHOOK
Finosu sends call results to the receiver configured for your integration. The /call/webhook name identifies this contract; it is not a URL to call on api.finosu.com. Contact Finosu to configure delivery and validate a test call.

Payload

The webhook uses snake_case field names. REST call detail and scheduled-call responses have separate schemas; their camelCase names do not apply here.
  • call_id is the Finosu call UUID; use it with GET /calls/{id} to look up the call. It stays the same across retries, including deliveries queued before this field was added.
  • customer_id is your external customer reference.
  • loan_id is the external loan reference supplied as loanId during enrollment (POST /customers/schedule/sync). It comes from the loan linked to this call’s schedule and is omitted when that reference is unavailable. Finosu does not infer it from the customer’s latest loan or send an internal loan UUID. Existing deliveries queued before this field was introduced may omit it.
  • call_id, customer_id, transcript, recording_url, and timestamp are always present. Unavailable transcript or recording data is represented by an empty string.
  • to_phone_number and flags are omitted when unavailable or empty. summarization is omitted when no summary data exists; it can be an empty string if a stored summary object has no note. These fields are not sent as null.
  • timestamp is the UTC time when the worker prepares the delivery attempt, not the call time. Worker retries refresh it; immediate HTTP retries reuse the same body. REST call detail’s timestamp is the call record’s creation time.
  • recording_url expires one hour after generation. Download a recording before expiry if you need to retain it; storing the URL does not preserve access.

Retries and deduplication

Every request includes an Idempotency-Key header that is stable for the call and destination and is reused across retries. Treat it as opaque. Use it as the delivery deduplication key. Use call_id to correlate the call in your records; Idempotency-Key identifies its delivery to a particular destination. Do not deduplicate by the body or timestamp: a worker retry may refresh the timestamp and recording URL. Durably record the key and accept the event before returning a 2xx response. Coordinate that record with your processing or durable queue so simultaneous retries cannot apply the same business action twice. A duplicate that has already been accepted should also receive a 2xx response. Non-2xx responses and network errors are retried within configured limits. The header enables deduplication; it does not itself guarantee exactly-once processing or unlimited delivery.

Other call objects

The public flag catalog describes a public subset for a selected task type. Receivers should tolerate additional flag codes.

Headers

Idempotency-Key
string
required

Opaque stable key for this call and destination, reused across retries. Persist the key and durably accept each delivery once; the header alone does not provide exactly-once processing.

Body

application/json

Call result delivery

Outbound call-result webhook. Field names are snake_case; REST call detail uses CallResponse instead.

call_id
string<uuid>
required

Finosu call UUID for correlation with GET /calls/{id}. Stable across retries, including deliveries queued before deployment. Use Idempotency-Key for delivery deduplication.

customer_id
string
required

Your external customer reference ID.

transcript
string
required

Call transcript; an empty string when unavailable.

recording_url
string
required

One-hour presigned recording URL generated for each worker delivery attempt, or an empty string when unavailable. Download the recording before the link expires.

timestamp
string<date-time>
required

UTC time when the worker prepares this delivery attempt, not when the call occurred. Refreshed on worker retries; immediate HTTP retries reuse the same body.

loan_id
string

External loan reference supplied as loanId during enrollment, from the loan linked to this call's schedule. Omitted when no associated loan reference is available; never inferred from another customer loan.

to_phone_number
string

Called phone number; omitted when unavailable.

Example:

"+14155551234"

flags
string[]

Call outcome flag codes. Omitted when there are no flags. Not postProcessingFlags. Handle unknown codes; the public task-type catalog is a subset.

Example:
summarization
string

Summary text when summary data exists. Omitted when no summary data exists; may be an empty string when the stored summary object has no note.

Response

2XX

Any 2xx acknowledges the delivery. Non-2xx responses and transport errors are retried within configured limits.