Webhooks

Preview feature. Webhooks are currently in preview. Seamless delivery is not guaranteed, and the API, payload shape, and behaviour are likely to change in future releases.

Quarterzip can notify your systems in real time when an event happens in your workspace. You register an HTTPS endpoint and Quarterzip sends a signed POST request to it whenever a relevant event occurs. Today there is a single event — call.completed — sent once a call has finished and its transcript and metadata are available.

Set up an endpoint

In the Quarterzip dashboard, go to Settings → Webhooks.
Enter the HTTPS URL that should receive events.
Toggle Enabled on and save.

When you save a URL for the first time, Quarterzip generates a signing secret and displays it once. Copy it immediately and store it somewhere secure, such as a secrets manager — never in source control. You’ll need it to verify that incoming requests genuinely came from Quarterzip, and it will not be shown again.

The endpoint URL must use https and must resolve to a public IP address. Localhost, private-network, and link-local addresses are rejected.

You can configure one endpoint per workspace.

Rotating the secret

If a secret is ever leaked, click Rotate secret on the same settings page. A new secret is generated and shown once.

Rotation takes effect immediately. The old secret stops verifying as soon as you rotate, so update your endpoint with the new value promptly to avoid rejecting deliveries in between.

Verify the signature

Always verify the signature before trusting a webhook. It proves the request came from Quarterzip and wasn’t tampered with in transit.

Quarterzip signs every delivery using the open Standard Webhooks specification, so you can use the official standardwebhooks libraries to verify with a few lines of code. Each request includes three headers:

Header	Description
`webhook-id`	Unique ID for this delivery (for example, `call_completed_abc123`).
`webhook-timestamp`	Send time as a Unix timestamp (seconds).
`webhook-signature`	Space-separated list of `v1,<base64-signature>` values.

Verify against the raw request body, exactly as received. Do not parse and re-serialize the JSON first, or the signature won’t match.

# pip install standardwebhooks
from standardwebhooks import Webhook

# The whole "whsec_..." string shown when you created or rotated the secret.
WEBHOOK_SECRET = "whsec_..."

def handle_webhook(raw_body: bytes, headers: dict[str, str]) -> None:
    wh = Webhook(WEBHOOK_SECRET)

    # Raises on an invalid signature or an out-of-tolerance timestamp.
    payload = wh.verify(raw_body, headers)

    if payload["type"] == "call.completed":
        process_completed_call(payload["data"])

// npm install standardwebhooks
import { Webhook } from 'standardwebhooks';

// The whole "whsec_..." string shown when you created or rotated the secret.
const WEBHOOK_SECRET = 'whsec_...';

// `rawBody` must be the exact bytes/string received, not a re-serialized object.
function handleWebhook(rawBody: string, headers: Record<string, string>) {
  const wh = new Webhook(WEBHOOK_SECRET);

  // Throws on an invalid signature or an out-of-tolerance timestamp.
  const payload = wh.verify(rawBody, headers) as { type: string; data: unknown };

  if (payload.type === 'call.completed') {
    processCompletedCall(payload.data);
  }
}

The library also enforces a timestamp tolerance, which protects you against replayed deliveries.

Delivery, Retries & Timeouts

Return any 2xx status code to acknowledge a webhook. Anything else — 4xx, 5xx, a connection error, or a timeout — is treated as a failed delivery and will be retried. Acknowledge first, process later. Your endpoint should do the minimum needed to persist the event (write it to a queue or a table) and return 2xx immediately. Doing the work inline risks hitting the timeout, and a timeout means redelivering an event you have already processed. Each delivery attempt is given 30 seconds. An attempt that hasn’t completed in that window is abandoned and retried. A failed delivery is retried up to 10 times with exponential backoff, starting at ~10 seconds and capping at 1 hour. After the final retry the event is dropped. Retries reuse the same webhook-id header as the original attempt. You should expect duplicates even when nothing looks wrong. A response we never received — because it arrived after the timeout, or the connection dropped mid-response — is indistinguishable from a failure, so we may retry an event your endpoint already processed successfully.

Events

`call.completed`

Quarterzip sends this event after a call finishes processing. The request is a JSON POST with Content-Type: application/json.

Example payload

{
  "type": "call.completed",
  "timestamp": "2026-08-03T10:44:12.318402+00:00",   // ISO 8601, UTC, when we built the payload
  "data": {
    "call_id": "abc123",
    "workspace_id": "ws_123",
    "deployment_id": "dep_123",
    "started_at": "2026-08-03T10:31:02.114000+00:00", // ISO 8601, always present
    "ended_at": "2026-08-03T10:44:09.882000+00:00",   // ISO 8601, or null
    "is_test": false,          // true for test calls
    "is_coaching": false,    // true for coaching calls
    "is_phone": false,        // true if call came over the phone
    "is_sdk": true,            // true if call came through SDK integration
    "call_quality_rating": null,          // int 1–5, or null
    "product_experience_rating": null,  // int 1–5, or null
    "transcript": [
      { "speaker": "User",  "text": "..." },
      { "speaker": "Agent", "text": "..." }
    ]
  }
}

Payload size and transcript truncation

Payloads are capped at 1 MB. Transcripts are omitted if the payload would otherwise exceed this limit. When this occurs, transcript_truncated will be set true.

{
  "type": "call.completed",
  "data": {
    "call_id": "abc123",
    "transcript": [],
    "transcript_truncated": true
  }
}

Troubleshooting

Symptom	Likely cause
Not receiving any events	Endpoint is not Enabled, or no real calls are completing.
Signature verification fails	Verifying against a re-serialized body instead of the raw bytes, or using an old secret after a rotation.
Can’t save the URL	URL must be `https` and resolve to a public IP — private and localhost addresses are rejected.
Lost the signing secret	The secret is only shown once — rotate it from Settings → Webhooks to generate a new one.

Quarterzip

Documentation

Security & Privacy

Set up an endpoint

Rotating the secret

Verify the signature

Delivery, Retries & Timeouts

Events

`call.completed`

Example payload

Payload size and transcript truncation

Troubleshooting

​Set up an endpoint

​Rotating the secret

​Verify the signature

​Delivery, Retries & Timeouts

​Events

​call.completed

​Example payload

​Payload size and transcript truncation

​Troubleshooting

Set up an endpoint

Rotating the secret

Verify the signature

Delivery, Retries & Timeouts

Events

`call.completed`

Example payload

Payload size and transcript truncation

Troubleshooting