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.

whsec_abc123xyz...

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 a signature header:

X-Affonso-Signature: t=1704067200,v1=abc123...

The header contains:

t - Unix timestamp of when the signature was generated
v1 - The HMAC-SHA256 signature

Verification Process

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const [timestampPart, signaturePart] = signature.split(',');
  const timestamp = timestampPart.replace('t=', '');
  const expectedSignature = signaturePart.replace('v1=', '');
  
  // Check timestamp is within 5 minutes
  const currentTime = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTime - parseInt(timestamp)) > 300) {
    return false;
  }
  
  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(computedSignature)
  );
}

import hmac
import hashlib
import time

def verify_webhook_signature(payload: str, signature: str, secret: str) -> bool:
    parts = signature.split(',')
    timestamp = parts[0].replace('t=', '')
    expected_signature = parts[1].replace('v1=', '')
    
    # Check timestamp is within 5 minutes
    current_time = int(time.time())
    if abs(current_time - int(timestamp)) > 300:
        return False
    
    # Compute expected signature
    signed_payload = f"{timestamp}.{payload}"
    computed_signature = hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected_signature, computed_signature)

package main

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

func verifyWebhookSignature(payload, signature, secret string) bool {
    parts := strings.Split(signature, ",")
    timestamp := strings.TrimPrefix(parts[0], "t=")
    expectedSignature := strings.TrimPrefix(parts[1], "v1=")
    
    // Check timestamp is within 5 minutes
    ts, _ := strconv.ParseInt(timestamp, 10, 64)
    if abs(time.Now().Unix()-ts) > 300 {
        return false
    }
    
    // Compute expected signature
    signedPayload := timestamp + "." + payload
    h := hmac.New(sha256.New, []byte(secret))
    h.Write([]byte(signedPayload))
    computedSignature := hex.EncodeToString(h.Sum(nil))
    
    return hmac.Equal([]byte(expectedSignature), []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

Your endpoint should respond within 30 seconds. 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
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