Trovacast

Get started

Receive webhooks

Register an HTTPS endpoint, verify each delivery's signature, deduplicate on the event id and catch up after an outage.

What you need

  • A public HTTPS URL your server answers on (port 443, 80, or 1024 and up).
  • An API key with webhooks:manage, plus the read scope of every event you subscribe to — messages:read for message.*, calls:read for call.* and so on (Scopes).

1. Register the endpoint

Create an endpoint
curl -X POST 'https://api.trovacast.com/v1/webhook-endpoints' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: webhook-messages-v1' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://apps.example.com/trovacast/webhook",
  "events": [
    "message.sent",
    "message.delivered",
    "message.failed",
    "message.received"
  ],
  "description": "Message updates"
}'

The answer carries the endpoint's secret (whsec_…) — once. Store it with your other secrets, for example as TROVACAST_WEBHOOK_SECRET.

2. Verify, answer, then handle

Read the raw body, verify the Trovacast-Signature header against your secret, answer 2xx within 10 seconds, and only then do the work — on a queue if it is slow. Deduplicate on the event id: every event is delivered at least once.

Node.js (Express) (javascript)
import express from 'express';
import { constructWebhookEvent } from '@trovacast/sdk/webhooks';

const app = express();
const seen = new Set(); // use your database in production

app.post('/trovacast/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = constructWebhookEvent({
      payload: req.body,
      header: req.headers['trovacast-signature'],
      secrets: [process.env.TROVACAST_WEBHOOK_SECRET],
    });
  } catch {
    return res.sendStatus(400);
  }
  res.sendStatus(200);
  if (seen.has(event.id)) return;
  seen.add(event.id);
  if (event.type === 'message.failed') {
    console.log('failed', event.data.message.id, event.data.message.failure);
  }
});

app.listen(3000);
Python (Flask) (python)
import os

from flask import Flask, request
from trovacast.webhooks import TrovacastWebhookError, construct_webhook_event

app = Flask(__name__)
seen = set()  # use your database in production

@app.post("/trovacast/webhook")
def webhook():
    try:
        event = construct_webhook_event(
            payload=request.get_data(),
            header=request.headers.get("Trovacast-Signature"),
            secrets=[os.environ["TROVACAST_WEBHOOK_SECRET"]],
        )
    except TrovacastWebhookError:
        return "", 400
    if event["id"] not in seen:
        seen.add(event["id"])
        if event["type"] == "message.failed":
            print("failed", event["data"]["message"]["id"])
    return "", 200

In another language, apply the signature rule directly — an HMAC-SHA256 over <t>.<raw body> compared in constant time — and check your code against its test vector.

3. Send a test event

Test the endpoint
curl -X POST 'https://api.trovacast.com/v1/webhook-endpoints/ENDPOINT_ID/test' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
200 OK (json)
{
  "object": "webhook_test",
  "success": true,
  "statusCode": 200,
  "error": null,
  "durationMs": 182,
  "eventId": "EVENT_ID"
}

The test sends a synthetic webhook.test event, signed like any delivery, and reports your server's answer. A failure names its class (TIMEOUT, CONNECTION_FAILED, HTTP 500, …), never the socket detail.

4. Catch up after an outage

Failed deliveries are retried for about three days. If your server was down longer — or answered 2xx and lost an event — read the events back (kept 30 days) or resend the failed deliveries in bulk:

Resend failed deliveries since a moment
curl -X POST 'https://api.trovacast.com/v1/webhook-endpoints/ENDPOINT_ID/deliveries/resend' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: resend-2026-11-04' \
  -H 'Content-Type: application/json' \
  -d '{
  "since": "2026-11-04T00:00:00.000Z"
}'
200 OK — call again while hasMore is true (json)
{
  "object": "webhook_delivery_resend",
  "resent": 214,
  "hasMore": false
}

Next steps