Webhooks

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

Webhooks allows Quarterzip to provide you with real-time event notifications. By registering a secured URL endpoint, Quarterzip will send a signed POST request in response to certain events occurring in your workspace. Support events include: call.completed, call.recording.ready

Configuring Webhooks

Webhooks depend on you providing a URL endpoint to a secured HTTPS server that can receive & respond to delivered messages from Quarterzip. Testing can performed with online services such as webhook.site, or against locally running servers using ngrok or Cloudflare tunnels.

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

You can configure one endpoint per workspace.

Secured with Signatures

Quarterzip signs every delivery using the open Standard Webhooks specification. This includes a webhook-signature header value that you can verify against to ensure that the webhook message was delivered by Quarterzip and was not tampered in transit. Verifying the signature is optional. Webhook message are not encoded.

Verifying the signature

When you save a URL for the first time, Quarterzip generates a signing secret. 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.

The official standardwebhooks libraries can be used to verify a webhook delivery with only a few lines of code.

# uv pip install standardwebhooks
from standardwebhooks import Webhook

# Generated from your workspace's SDK settings page
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);
  }
}

Rotating the secret

A new signing secret can be generated from the workspace’s SDK settings page. Rotation takes effect immediately.

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 3 times with fixed backoff: 1, 5, & 15 minutes. After the final retry the event is dropped and the endpoint is considered unreachable - this will automatically disable the workspace’s webhooks. 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.

Best Practices

While webhooks is in preview, ensure that your server’s endpoint handler responds with a 2xx status code. Consider wrapping the handler in a try...except, try...catch, or equivalent. Failing to do so risks the workspace’s registered webhook to be automatically deactivated; see Delivery, Retries & Timeouts.

Evaluate received messages by event type. The likelihood of new event types encourages the following pattern:

if payload["type"] == "call.completed":
    process_completed_call(payload["data"])
elif payload["type"] == "call.recording.ready"
    process_completed_call(payload["data"])
else:
    print(f"Unsupported event type recieved: {payload['type']})

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
    "external": {  // Metadata provied by via SDK/URL parameters
      "user_id": "jandoe_123",
      "email": "jane.doe@example.com",
      "display_name": "Jane Doe",
    },
    "transcript": [
      { "speaker": "User",  "text": "..." },
      { "speaker": "Agent", "text": "..." }
    ]
  }
}

`call.recording.ready`

Quarterzip sends an event after a call’s recording is ready for download. The delivery of this event is not guaranteed; calls may not have recordings, or workspaces may have recordings disabled.

Example Payload

{
  "type": "call.recording.ready",
  "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",
    "recording_url": "https://...",  // A pre-signed expirying download URL
    "recording_url_expires_at": false,  // ISO 8601
  }
}

Troubleshooting

Symptom	Likely cause
Not receiving any events	Endpoint is not Enabled, or supported events are occurring.
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

Configuring Webhooks

Secured with Signatures

Verifying the signature

Rotating the secret

Delivery, Retries & Timeouts

Best Practices

Events

`call.completed`

Example payload

`call.recording.ready`

Example Payload

Troubleshooting

​Configuring Webhooks

​Secured with Signatures

​Verifying the signature

​Rotating the secret

​Delivery, Retries & Timeouts

​Best Practices

​Events

​call.completed

​Example payload

​call.recording.ready

​Example Payload

​Troubleshooting

Configuring Webhooks

Secured with Signatures

Verifying the signature

Rotating the secret

Delivery, Retries & Timeouts

Best Practices

Events

`call.completed`

Example payload

`call.recording.ready`

Example Payload

Troubleshooting