GUIDES

Webhooks: signed events & retries

Tokely webhook events, HMAC signature verification, delivery retries and replay behavior.

Events

payment.succeeded: funds have been credited to the account. payment.failed: checkout or payment ended unsuccessfully. request.failed: an error was recorded by the gateway (opt in). webhook.test: a test requested by the account owner.

Events are account scoped. Payloads exclude prompts, completions, API keys and internal credentials. Request events require an entry in the gateway log; failures before logging are outside this event stream.

Verify the signature

The Tokely-Signature header contains t=timestamp,v1=hex_signature. Compute HMAC-SHA256 using the signing secret as a UTF-8 string over the timestamp, a period, and the exact raw request bytes. Compare signatures in constant time and reject timestamps outside five minutes. Reject the HTTP request if verification raises an error, before processing the event.

Secret rotation takes effect immediately. An attempt already in flight may carry the previous signature. Store the newly shown secret securely.

import hashlib, hmac, time

try:
    parts = dict(part.split('=', 1) for part in signature.split(','))
    timestamp = int(parts['t'])
    supplied_signature = parts['v1']
except (KeyError, ValueError):
    raise ValueError('Invalid webhook signature')

if abs(time.time() - timestamp) > 300:
    raise ValueError('Webhook timestamp outside tolerance')
expected = hmac.new(secret.encode(), parts['t'].encode() + b'.' + raw_body,
                    hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, supplied_signature):
    raise ValueError('Invalid webhook signature')

Delivery and replay

Return any 2xx response within 10 seconds. Redirects are not followed. Non-2xx responses and network errors retry with exponential delay and jitter, starting at about 30 seconds and capped at six hours, up to 12 attempts or 72 hours per delivery cycle. Exhausted deliveries enter the dead-letter state.

Deduplicate effects using the JSON id or the Tokely-Event-Id header. Delivery is at least once: a lost acknowledgment can cause a duplicate. Replay preserves the original event ID and payload and starts a new delivery cycle. It never recredits payments or reissues inference.

Pausing keeps events queued within the same retry window. The delivery journal preserves attempt timestamps and HTTP response codes. Recipient response bodies are discarded. Deleting an endpoint cancels queued deliveries; a request already in flight may still arrive.

Event envelope

New endpoints receive future events. Test delivery is sent only when you explicitly request it. Budgets, batch and task events are not advertised until their producers exist.

{
  "id": "event-id", "type": "payment.succeeded", "version": 1,
  "account_id": "account-uuid", "occurred_at": "2026-10-07T12:00:00+00:00",
  "resource_id": "payment-order-id",
  "data": { "amount_usd": 25, "status": "credited" }
}

EXPLORE DOCUMENTATION

IntroductionConnect your app to AI models through one familiar API. This is your guide to building with Tokely.QuickstartMake your first Tokely request in three steps.API keysConnect securely with a key from your Tokely dashboard.ModelsChoose an available model and use its exact ID in your request.PlaygroundUse the Tokely Playground to test prompts before writing code.Use your existing appConnect an existing OpenAI-compatible application to Tokely.Chat CompletionsGenerate responses from text messages and supported inline images or PDFs.ResponsesUse stateless text and supported multimodal input with the Responses API.EmbeddingsTurn text into vectors for search, RAG, clustering and classification with the OpenAI-compatible /v1/embeddings endpoint.Claude Code and the Messages APIPoint Claude Code or the Anthropic SDK at Tokely. Use the native /v1/messages endpoint with streaming, tools and prompt caching.Images and PDFsSend inline images and PDFs to compatible models through Chat Completions or Responses.Images, video & audioGenerate media with your Tokely API key and account balance.Errors & limitsDiagnose failed requests and keep your integration within service limits.StreamingDisplay generated text as it arrives with server-sent events.Function callingLet a model request a function, then execute it in your application.Structured outputRequest JSON output or a defined schema from a compatible model.Usage & billingModel prices, account balance and output reservations.WebhooksTokely webhook events, HMAC signature verification, delivery retries and replay behavior.
Use Tab to browse results ESC to close