Webhooks

Spenza can push operator-originated SMS and voice events to a URL you control, instead of you polling for them. You manage this through a REST collection — register a webhook, list your registrations, update or delete them — and every delivery is signed so you can verify it actually came from Spenza.

The event model

You register one webhook per operator + network combination, choosing which event category it covers:

`eventType`	Delivers
`sms`	Inbound SMS events for that operator/network.
`voice`	Inbound voice events for that operator/network.
`both`	Both.

There’s at most one registration per (account, operator, network) — eventType isn’t part of that key, so registering a second event type for the same operator+network replaces the first rather than adding a second registration. Registering again for an existing combination without update: true in the body returns 409 CONFLICT.

Registering voice (or both) always succeeds if the operator/network combination itself is valid — there’s no registration-time check that voice is actually enabled the way there is for sms. But you won’t actually receive voice events for a line unless that line’s active plan includes voice support (a plan with no voice allowance leaves voice disabled on the number). Make sure the SIMs you expect voice events for are on a voice-capable plan before assuming a registered voice webhook is misbehaving if nothing arrives.

Registering a webhook

curl -X POST "https://api.spenza.com/api/v1.1/webhooks" \
  -H "Authorization: Bearer $SPENZA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operator": "SpenzaJ",
    "network": "T-Mobile",
    "eventType": "sms",
    "authentication": { "type": "bearer", "token": "a-secret-you-choose" },
    "webhookUrls": { "messageUrl": "https://partner.example.com/hooks/sms" },
    "retryPolicy": { "maxAttempts": 5, "backoffStrategy": "exponential", "initialDelaySeconds": 5, "maxDelaySeconds": 300 },
    "status": "active"
  }'

The response echoes your registration back with credential fields masked as "***ENCRYPTED***", plus a one-time signingSecret (format whsec_<64 hex chars>) — see Verifying delivery signatures below. Manage registrations as a normal REST collection:

curl "https://api.spenza.com/api/v1.1/webhooks" -H "Authorization: Bearer $SPENZA_TOKEN"
curl "https://api.spenza.com/api/v1.1/webhooks/{id}" -H "Authorization: Bearer $SPENZA_TOKEN"
curl -X PUT "https://api.spenza.com/api/v1.1/webhooks/{id}" -H "Authorization: Bearer $SPENZA_TOKEN" -d '{ }'
curl -X DELETE "https://api.spenza.com/api/v1.1/webhooks/{id}" -H "Authorization: Bearer $SPENZA_TOKEN"

None of the read/list/get calls ever return signingSecret again — only the create/upsert response does. Store it the moment you get it; losing it means re-registering.

How your endpoint authenticates the caller

Separately from payload signing, authentication (type: basic | bearer | api_key | none) protects your webhook URL — Spenza presents this credential when it calls you, so your endpoint can reject callers that don’t have it. Set it to bearer or basic, not none, so your endpoint isn’t open to anyone who discovers its URL.

Verifying delivery signatures

Every delivery (including test events) carries two headers:

X-Spenza-Signature: t=1719792000,v1=9f8b3c2e1a4d6f7b8c9e0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d
X-Spenza-Timestamp: 1719792000

X-Spenza-Timestamp is Unix seconds. The v1 value in X-Spenza-Signature is an HMAC-SHA256 computed over the exact string ${timestamp}.${rawBody}, keyed with your registration’s signingSecret — a Stripe-compatible scheme, chosen so most partners can reuse an existing verifier:

const crypto = require("crypto");

function verifySpenzaSignature(rawBody, signatureHeader, timestampHeader, signingSecret) {
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest("hex");
  const provided = signatureHeader.split(",").find((p) => p.startsWith("v1="))?.slice(3);
  return provided && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

Compare against rawBody (the exact bytes received), not a re-serialized version of the parsed JSON — re-serialization can silently change key order or whitespace and break the comparison. A 5-minute tolerance window on X-Spenza-Timestamp is documented convention (WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300) — Spenza doesn’t enforce it on the sending side; it’s your endpoint’s own replay-protection check to make if you want it.

Retry behavior

Delivery retries are configurable per registration via retryPolicy:

Field	Purpose	Default
`maxAttempts`	How many times Spenza retries a failed delivery (1–10).	`3`
`backoffStrategy`	`fixed`, `exponential`, or `linear`.	`exponential`
`initialDelaySeconds`	Delay before the first retry (1–60).	`5`
`maxDelaySeconds`	Ceiling on the delay between retries (60–3600).	`300`

A delivery is considered successful when your endpoint returns any 2xx response — respond fast and do your processing after responding, not before. After 10 consecutive delivery failures, a registration’s status automatically flips to suspended; check GET /api/v1.1/webhooks periodically, or the status field on GET /api/v1.1/webhooks/{id}, to catch this.

Testing a registration

Send a one-off synthetic event without waiting for a real operator event:

curl -X POST "https://api.spenza.com/api/v1.1/webhooks/{id}/test" \
  -H "Authorization: Bearer $SPENZA_TOKEN" -H "Content-Type: application/json" \
  -d '{ "eventType": "webhook.test" }'

This sends one attempt (no retries) to whichever URL is configured, in priority order messageUrl → callbackMessageUrl → voiceUrl → callbackVoiceUrl. It’s recorded in the deliveries list but doesn’t count toward the 10-consecutive-failure auto-suspend threshold, so you can rehearse your handler without risking a live registration’s status.

Inspecting and redelivering past events

curl "https://api.spenza.com/api/v1.1/webhook-deliveries?webhookId={id}&status=FAILED" \
  -H "Authorization: Bearer $SPENZA_TOKEN"

This never returns the delivered payload, response body, or raw error text — just status/timing metadata (deliveryId, webhookId, eventType, status, responseCode, attempt, deliveredAt). If you find a FAILED delivery worth retrying manually (after fixing your handler, for example), redeliver the original event and body to its original endpoint:

curl -X POST "https://api.spenza.com/api/v1.1/webhook-deliveries/{deliveryId}/redeliver" \
  -H "Authorization: Bearer $SPENZA_TOKEN"

This queues the redelivery and returns 202 immediately with a new PENDING delivery record — it runs on a background queue, not the request cycle, so poll the deliveries list for the outcome.

Idempotency

No delivery/event ID for dedup yet. There’s no dedicated event ID field in the delivered payload itself. Retries (both automatic and manual redelivery) mean a given event may be delivered more than once; design your handler to be safe to run twice — for example, keying off whatever naturally-unique fields the payload contains (message SID, timestamp + from/to number) once you’ve inspected a real payload, and ignoring exact duplicates.

Example payloads

Payload schema is being published. The exact JSON body sent to messageUrl/voiceUrl on a real inbound SMS or voice event isn’t published yet. Until then, register a webhook against a test endpoint (a request-inspection tool) and use POST /api/v1.1/webhooks/{id}/test or a real event to capture the actual shape before writing a parser.

Next steps

Security & Best Practices for handling the credentials in authentication and signingSecret.
API Reference → Webhooks (sidebar) for the full field-level schema of the registration and delivery objects.

Overview

Build

Reference

Help

API Reference

The event model

Registering a webhook

How your endpoint authenticates the caller

Verifying delivery signatures

Retry behavior

Testing a registration

Inspecting and redelivering past events

Idempotency

Example payloads

Next steps

​The event model

​Registering a webhook

​How your endpoint authenticates the caller

​Verifying delivery signatures

​Retry behavior

​Testing a registration

​Inspecting and redelivering past events

​Idempotency

​Example payloads

​Next steps

The event model

Registering a webhook

How your endpoint authenticates the caller

Verifying delivery signatures

Retry behavior

Testing a registration

Inspecting and redelivering past events

Idempotency

Example payloads

Next steps