Copy page

Guides

Webhooks

An outbound webhook is an HTTP POST that Ringtime sends to your system. It tells you what happened in a conversation, without you polling for it. Ringtime sends one POST per event to the single endpoint your organization registered.

Registering your endpoint

You cannot register a webhook endpoint with your API key. Registration is not part of the public API today.

Ask Ringtime to set it up. Send your HTTPS receiver URL to success@ringtime.ai. Ringtime registers the URL and gives you a signing secret that starts with whsec_.

Ringtime shows the signing secret once, at registration. Store it in your own secret store. If you lose it, or you think it leaked, ask Ringtime to rotate it. A rotation issues a new secret and old signatures stop verifying.

The envelope

Every webhook body has the same four top-level fields.

Code
{
  "event": "task.completed",
  "schema_version": 1,
  "occurred_at": "2026-09-15T14:22:05Z",
  "data": {}
}

Field	Type	What it is
event	string	The event type. task.completed or interaction.finalized.
schema_version	integer	The envelope version. 1 today.
occurred_at	string	When the event happened, ISO 8601 in UTC with a Z suffix. Not when the POST was sent.
data	object	The body for this event type. The shape depends on event.

data is an open object. Ringtime adds fields over time and never removes one. Ignore keys you do not know, and do not fail on them.

The two events

Event	When	On by default
task.completed	The task reached its final state. One per task.	Yes
interaction.finalized	One contact attempt finished. One per attempt.	No

interaction.finalized is opt-in. Ask Ringtime to add it to your endpoint if you want per-attempt detail. A task with three attempts then sends three interaction.finalized events and one task.completed.

task.completed

The business result of the whole task.

Field	Type	What it is
id	string	The task id, for example task_01HZX9Q2K9.
campaign	object	The campaign that produced the task. See below.
status	string	The final task status. completed today.
outcome	string	The single headline result. See the values below.
participant	object	The person Ringtime contacted. See below.
ids	array	Your external ids, echoed from the trigger. Empty for a task you did not trigger.
context	object	The context you sent on the trigger, returned as sent. Empty for a task you did not trigger.
business_outcomes	object	The full picture of what the task achieved. See below.

outcome is one of booked, qualified, not_eligible, screened, escalated, callback, declined, opted_out, or none. none means Ringtime reached the person but recorded no business result. The set can grow, so treat an unknown value as none rather than failing. outcome is a summary. Read business_outcomes for the detail.

campaign carries external_id, the routing key you triggered with, and name, the campaign name in the participant's language. Both are null when Ringtime has no campaign for the task.

participant carries first_name, last_name, phone in E.164, and language, a BCP 47 code or null.

Each entry in ids carries source, type and value, exactly as you sent them on the trigger.

business_outcomes holds the outcomes Ringtime captured across every attempt of the task. The keys are bookings and side_effects (arrays, one entry per occurrence) and screening_assessment, lead_qualification, opt_out, disinterest, not_eligible, escalation and callback_preference (an object or null, the most recent one wins).

Example

Code
{
  "event": "task.completed",
  "schema_version": 1,
  "occurred_at": "2026-09-15T14:22:05Z",
  "data": {
    "id": "task_01HZX9Q2K9",
    "campaign": {
      "external_id": "warehouse-nl",
      "name": "Warehouse operator"
    },
    "status": "completed",
    "outcome": "screened",
    "participant": {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+15555550100",
      "language": "nl"
    },
    "ids": [
      { "source": "carerix", "type": "candidate", "value": "42881" },
      { "source": "carerix", "type": "application", "value": "90117" }
    ],
    "context": {
      "requisition": "REQ-118"
    },
    "business_outcomes": {
      "bookings": [],
      "screening_assessment": {
        "screening_flow_id": "sf_01HZX9Q2M2",
        "flow_name": "Warehouse intake",
        "language": "nl",
        "score": 78,
        "score_scale": "0_100",
        "threshold": 60,
        "answers": [
          {
            "position": 1,
            "screening_question_id": "sq_01HZX9Q2M3",
            "question": "Can you work early shifts?",
            "question_type": "yes_no",
            "category": "availability",
            "weight": "mandatory",
            "possible_answers": ["yes", "no"],
            "value": true,
            "source": "heard",
            "answer": "Yes, from 6am onwards.",
            "assessment": "positive"
          }
        ],
        "unanswered": [],
        "has_mandatory_fail": false,
        "has_soft_negative": false,
        "rationale": "All mandatory questions answered positively.",
        "recommended_next_step": "proceed"
      },
      "lead_qualification": null,
      "side_effects": [],
      "opt_out": null,
      "disinterest": null,
      "not_eligible": null,
      "escalation": null,
      "callback_preference": null
    }
  }
}

interaction.finalized

One contact attempt, with its transcript. Where task.completed says what the task achieved, this says whether Ringtime got through at all.

Field	Type	What it is
id	string	The interaction id, for example int_01HZX9Q2KA.
task_id	string or null	The parent task id. null when the interaction has no task.
campaign	object	Same shape as on task.completed.
participant	object	Same shape as on task.completed.
ids	array	Same shape as on task.completed.
channel	string	voice, whatsapp, sms, chat or slack.
direction	string	outbound or inbound.
started_at	string or null	When the session started, if it did.
ended_at	string or null	When the attempt ended, if known.
duration_secs	integer or null	Session length in seconds, when both ends are known.
reach	string or null	How far the attempt got. unreached, reached, engaged or resolved. Voicemail counts as unreached.
answer_type	string or null	How the attempt was answered, for example answered_by_human, answered_by_voicemail, not_answered, not_answered_busy or replied. null when it does not apply.
system_failure	boolean	true when Ringtime, not the person, failed the attempt.
transcript	array	The conversation, turn by turn.
business_outcome_events	array	The outcomes captured on this attempt.

Each transcript turn carries role (agent or participant), text, and at, the time of the turn. Voice turns are transcribed. The transcript carries speech only. Tool calls and their results never appear in it, and there is no recording link.

Each entry in business_outcome_events carries id, kind, payload, schema_version and occurred_at. kind names the shape of payload and can gain new values, so skip an entry whose kind you do not know and keep processing the rest.

Example

Code
{
  "event": "interaction.finalized",
  "schema_version": 1,
  "occurred_at": "2026-09-15T14:21:48Z",
  "data": {
    "id": "int_01HZX9Q2KA",
    "task_id": "task_01HZX9Q2K9",
    "campaign": {
      "external_id": "warehouse-nl",
      "name": "Warehouse operator"
    },
    "participant": {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+15555550100",
      "language": "nl"
    },
    "ids": [{ "source": "carerix", "type": "candidate", "value": "42881" }],
    "channel": "voice",
    "direction": "outbound",
    "started_at": "2026-09-15T14:18:02Z",
    "ended_at": "2026-09-15T14:21:48Z",
    "duration_secs": 226,
    "reach": "engaged",
    "answer_type": "answered_by_human",
    "system_failure": false,
    "transcript": [
      {
        "role": "agent",
        "text": "Hi Jane, this is Acme Staffing calling about the warehouse role.",
        "at": "2026-09-15T14:18:05Z"
      },
      {
        "role": "participant",
        "text": "Yes, I have a few minutes.",
        "at": "2026-09-15T14:18:11Z"
      }
    ],
    "business_outcome_events": [
      {
        "id": "boe_01HZX9Q2MB",
        "kind": "screening_assessment",
        "schema_version": 1,
        "occurred_at": "2026-09-15T14:21:40Z",
        "payload": {
          "screening_flow_id": "sf_01HZX9Q2M2",
          "flow_name": "Warehouse intake",
          "language": "nl",
          "score": 78,
          "score_scale": "0_100",
          "threshold": 60,
          "answers": [],
          "unanswered": [],
          "has_mandatory_fail": false,
          "has_soft_negative": false,
          "rationale": "All mandatory questions answered positively.",
          "recommended_next_step": "proceed"
        }
      }
    ]
  }
}

Verifying the signature

Verify every request before you trust it. Ringtime signs each POST with your secret, following the Standard Webhooks specification.

Three headers carry the proof.

Header	What it is
webhook-id	The event id. Stable across retries. Also your duplicate key.
webhook-timestamp	When the request was signed, in Unix seconds.
webhook-signature	v1, followed by the base64 signature.

The v1, inside webhook-signature is the Standard Webhooks tag for the HMAC-SHA256 algorithm. It is a fixed part of the header format, not a version number, and it never changes.

To verify:

1. Take the key. Strip the whsec_ prefix from your secret and base64-decode the rest. Those raw bytes are the HMAC key.
2. Build the signed string. Join the webhook-id, the webhook-timestamp and the raw request body with a dot: id.timestamp.body. Use the body exactly as received. Do not parse and re-serialize it.
3. Compute HMAC-SHA256 over that string with the key, and base64-encode the result.
4. Compare v1, plus your result against the webhook-signature header, with a constant-time comparison.
5. Reject the request when webhook-timestamp is more than 300 seconds away from your own clock.

With a library

Use a Standard Webhooks library and you get all five steps for free. Pass the secret exactly as Ringtime gave it to you, whsec_ prefix included.

Code
from standardwebhooks.webhooks import Webhook

# Raises on a bad signature or an out-of-window timestamp.
Webhook(secret).verify(raw_body, request.headers)

By hand

Code
# The key: the secret without its prefix, base64-decoded.
KEY_HEX=$(printf '%s' "${RINGTIME_WEBHOOK_SECRET#whsec_}" \
  | openssl base64 -d | xxd -p | tr -d '\n')

# The signature over "id.timestamp.body".
printf '%s.%s.%s' "$WEBHOOK_ID" "$WEBHOOK_TIMESTAMP" "$RAW_BODY" \
  | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$KEY_HEX" -binary \
  | openssl base64 -A

Compare the output against the part of webhook-signature after v1,.

Delivery and retries

Delivery is at least once. Your endpoint can receive the same event twice, for example when your 2xx answer is lost on the way back. Make your handler idempotent. Keep the webhook-id of every event you processed and drop a repeat. A retry of the same event carries the same webhook-id and the same body, byte for byte.

Answer fast. Ringtime waits 10 seconds for a response, then treats the attempt as failed. Acknowledge with a 2xx status first and do your own work afterwards.

Ringtime retries when your endpoint answers 429, answers 5xx, times out, or cannot be reached. The wait grows exponentially from 1 minute, with full jitter, and is capped at 1 hour. On a 429 Ringtime honours a numeric Retry-After header, clamped to between 1 minute and 1 hour. A Retry-After given as a date is ignored.

Ringtime stops retrying in two cases:

• Your endpoint answers any other 4xx. That is a refusal, so Ringtime does not retry.
• 24 hours passed since the first attempt. The event is then dropped.

Requirements for your endpoint

• Use HTTPS. Plain HTTP is refused at registration.
• Be reachable from the public internet. Ringtime does not call private, loopback or link-local addresses.
• Do not put a username or password in the URL. Ringtime refuses such a URL.
• Answer within 10 seconds with a 2xx status.
• Be idempotent. Dedupe on the webhook-id header.
• Verify the signature before you act on the body.

Next

• How it works
• Getting started
• Errors