Webhook Setup

Prerequisites

Before setting up webhooks, ensure you have:

An active Affonso account with an affiliate program
A publicly accessible HTTPS endpoint to receive webhooks
The ability to verify webhook signatures (recommended)

Creating a Webhook Endpoint

Navigate to Webhooks

Go to your Affonso dashboard and select Settings → Webhooks from the sidebar.

Add New Endpoint

Click Add Endpoint and enter your webhook URL:

https://your-app.com/api/webhooks/affonso

Your endpoint must use HTTPS. HTTP endpoints are not supported for security reasons.

Select Events

Choose which events you want to receive. You can select:

All events - Receive every webhook event
Specific events - Only receive selected event types

Start with specific events you need. You can always add more later.

Copy Signing Secret

After creating the endpoint, copy your Signing Secret. You’ll need this to verify webhook signatures.

0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

The secret is a 64-character hex string. Use it as-is as a string key; do not hex-decode it.

Store this secret securely. It’s only shown once!

Verifying Webhook Signatures

Always verify webhook signatures to ensure requests are from Affonso.

Signature Header

Each webhook request includes two headers:

X-Affonso-Timestamp: 1704067200
X-Affonso-Signature: 4f2c8a1b9d3e7f0a6c5b8d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a

X-Affonso-Timestamp — Unix timestamp (seconds) of when the signature was generated
X-Affonso-Signature — lowercase hex HMAC-SHA256 of {timestamp}.{rawBody}, with no prefix

Verification Process

import crypto from 'crypto';

function verifyWebhookSignature(
  rawBody: string,
  timestampHeader: string | undefined,
  signatureHeader: string | undefined,
  secret: string
): boolean {
  if (!timestampHeader || !signatureHeader) {
    return false;
  }

  if (!/^\d+$/.test(timestampHeader)) {
    return false;
  }

  const timestamp = parseInt(timestampHeader, 10);
  const currentTime = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTime - timestamp) > 300) {
    return false;
  }

  const signedPayload = `${timestampHeader}.${rawBody}`;
  const computedSignature = crypto
    .createHmac('sha256', secret) // UTF-8 string key; do not hex-decode
    .update(signedPayload)
    .digest('hex');

  const expected = Buffer.from(signatureHeader);
  const computed = Buffer.from(computedSignature);
  if (expected.length !== computed.length) {
    return false;
  }

  return crypto.timingSafeEqual(expected, computed);
}

import hmac
import hashlib
import time

def verify_webhook_signature(
    raw_body: str,
    timestamp_header: str | None,
    signature_header: str | None,
    secret: str,
) -> bool:
    if not timestamp_header or not signature_header:
        return False

    if not timestamp_header.isdigit():
        return False

    timestamp = int(timestamp_header)
    if abs(int(time.time()) - timestamp) > 300:
        return False

    signed_payload = f"{timestamp_header}.{raw_body}"
    computed_signature = hmac.new(
        secret.encode("utf-8"),  # string key; do not hex-decode
        signed_payload.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(signature_header, computed_signature)

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strconv"
    "time"
)

func abs(n int64) int64 {
    if n < 0 {
        return -n
    }
    return n
}

func verifyWebhookSignature(rawBody, timestampHeader, signatureHeader, secret string) bool {
    if timestampHeader == "" || signatureHeader == "" {
        return false
    }

    ts, err := strconv.ParseInt(timestampHeader, 10, 64)
    if err != nil {
        return false
    }

    if abs(time.Now().Unix()-ts) > 300 {
        return false
    }

    signedPayload := timestampHeader + "." + rawBody
    h := hmac.New(sha256.New, []byte(secret)) // UTF-8 string key; do not hex-decode
    h.Write([]byte(signedPayload))
    computedSignature := hex.EncodeToString(h.Sum(nil))

    return hmac.Equal([]byte(signatureHeader), []byte(computedSignature))
}

Responding to Webhooks

Your endpoint must respond correctly for webhooks to be considered delivered.

Success Response

Return a 2xx status code to acknowledge receipt:

{
  "received": true
}

Response Time

Affonso waits up to 10 seconds for a response; slower responses count as failed and are retried. See the retry policy for how failed deliveries are retried. If processing takes longer:

Acknowledge the webhook immediately
Process the event asynchronously
Use a job queue for heavy processing

// Good: Acknowledge immediately, process async
app.post('/webhooks/affonso', async (req, res) => {
  // Verify signature first
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Acknowledge immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  await queue.add('process-webhook', req.body);
});

Testing Webhooks

Test Events

Use the Send Test Event button in your dashboard to send a test webhook to your endpoint.

Local Development

For local development, use a tunneling service:

ngrok http 3000
# Use the HTTPS URL as your webhook endpoint

lt --port 3000
# Use the HTTPS URL as your webhook endpoint

Troubleshooting

Webhook not receiving events

Verify your endpoint URL is correct and publicly accessible
Check that your endpoint returns a 2xx status code
Ensure you’ve selected the correct events to receive

Signature verification failing

Ensure you’re using the raw request body, not parsed JSON
Use the secret as a plain string (not hex-decoded, no prefix)
Sign {timestamp}.{rawBody} using the X-Affonso-Timestamp header
Check that your signing secret is correct
Verify the timestamp is within 5 minutes

Receiving duplicate events

Implement idempotency using the event id field
Store processed event IDs and skip duplicates

Overview

Events

Usage & Examples

Automation Tools

Prerequisites

Creating a Webhook Endpoint

Verifying Webhook Signatures

Signature Header

Verification Process

Responding to Webhooks

Success Response

Response Time

Testing Webhooks

Test Events

Local Development

Troubleshooting

​Prerequisites

​Creating a Webhook Endpoint

​Verifying Webhook Signatures

​Signature Header

​Verification Process

​Responding to Webhooks

​Success Response

​Response Time

​Testing Webhooks

​Test Events

​Local Development

​Troubleshooting

Prerequisites

Creating a Webhook Endpoint

Verifying Webhook Signatures

Signature Header

Verification Process

Responding to Webhooks

Success Response

Response Time

Testing Webhooks

Test Events

Local Development

Troubleshooting