Using Webhooks

Webhooks provide real-time notifications for events, such as campaign creation, updates, or deletions. To receive these notifications, you must specify a publicly accessible URL capable of receiving HTTP POST requests.

How it Works

When an event occurs, an HTTP POST request containing event details is sent to your specified URL. Your URL must return a 2xx HTTP status code for successful requests.

Webhooks are created via the Create Webhook API, where you define the triggering event using the channel field. Only one webhook is allowed per channel.

Retries and Validation

If your webhook URL is unreachable, we will retry sending the request up to 5 times within 1 minute, using exponential backoff. Retries occur only for 5xx or 429 HTTP status codes.

To ensure the authenticity and integrity of webhook deliveries, you should validate the signature. Topsort generates a signature using your webhook secret and the event payload, including it in the X-TS-Signature-256 HTTP header.

You can set your webhook secret during creation; otherwise, one will be generated. Store your secret securely.

Topsort uses HMAC hex digest (starting with sha256=) to compute the signature. You must recompute the hash on your server and compare it to the X-TS-Signature-256 header to verify the signature.

Example Signature Verification

import hmac
import hashlib

secret = "my-webhook-secret"
request = ... # incoming request from the webhook delivery

signature = hmac.new(
    key=secret.encode(),
    msg=await request.body(),
    digestmod=hashlib.sha256,
).hexdigest()

expected_signature = "sha256=" + signature
incoming_signature = request.headers["X-TS-Signature-256"]

if not hmac.compare_digest(incoming_signature, expected_signature):
    # The signature is not valid, do not process the delivery
else:
    # The signature is valid, process the delivery