Maybloc webhooks: events, signatures and retries

A webhook sends a POST to your server each time a transcript changes status, so you do not have to poll.

How do I add a webhook endpoint?

Add an endpoint under Webhooks in the console. The URL must be public HTTPS, redirects are not followed, and a workspace can have up to 10 endpoints. Copy the endpoint secret when it is shown.

Which events are sent?

transcript.queued
transcript.processing
transcript.completed
transcript.failed
transcript.canceled
transcript.addons.completed
transcript.addons.failed

What does a delivery look like?

{
  "id": "evt_…",
  "type": "transcript.completed",
  "created_at": "2026-10-06T09:14:03Z",
  "data": { "id": "6f1c…", "object": "transcript", "model": "calico-1-flash", "status": "completed" }
}

Each request has three headers: Maybloc-Timestamp (a Unix timestamp), Maybloc-Delivery (a unique delivery id) and Maybloc-Signature.

How do I verify the signature?

The signature is sha256= followed by the hex HMAC-SHA256 of the timestamp, a dot and the raw request body, keyed with your endpoint secret. Verify it on the raw body before parsing the JSON, compare in constant time, and reject timestamps older than 5 minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody is the request body exactly as received, before JSON parsing.
export function verify(rawBody, headers, secret) {
  const timestamp = headers["maybloc-timestamp"];
  const signature = headers["maybloc-signature"] ?? "";
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = "sha256=" + createHmac("sha256", secret).update(timestamp + "." + rawBody).digest("hex");
  return signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["Maybloc-Timestamp"]
    signature = headers.get("Maybloc-Signature", "")
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "sha256=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

How do I avoid processing a delivery twice?

Store the Maybloc-Delivery value of each delivery you handle and skip ids you have seen. A delivery can arrive more than once.

What happens when my server is down?

A delivery that does not get a success response is retried up to 6 times in total, waiting 30 seconds, 2 minutes, 10 minutes, 30 minutes and 2 hours between attempts. After the last attempt it is marked failed. You can see recent deliveries in the console.

Get started

Guides

Maybloc webhooks: events, signatures and retries

How do I add a webhook endpoint?

Which events are sent?

What does a delivery look like?

How do I verify the signature?

How do I avoid processing a delivery twice?

What happens when my server is down?

​How do I add a webhook endpoint?

​Which events are sent?

​What does a delivery look like?

​How do I verify the signature?

​How do I avoid processing a delivery twice?

​What happens when my server is down?

How do I add a webhook endpoint?

Which events are sent?

What does a delivery look like?

How do I verify the signature?

How do I avoid processing a delivery twice?

What happens when my server is down?