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:readformessage.*,calls:readforcall.*and so on (Scopes).
1. Register the 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.
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);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 "", 200In 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
curl -X POST 'https://api.trovacast.com/v1/webhook-endpoints/ENDPOINT_ID/test' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"{
"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:
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"
}'{
"object": "webhook_delivery_resend",
"resent": 214,
"hasMore": false
}