Testing Webhooks

Test your webhook integration before going to production.

Testing Locally with ngrok

Your webhook endpoint needs a public URL. Use ngrok to tunnel to your local server:

Start your local server

node server.js
# Listening on http://localhost:3000

Start ngrok

ngrok http 3000
# Forwarding: https://abc123.ngrok.io → http://localhost:3000

Use the ngrok URL as your webhook endpoint:

curl -X POST https://www.agentref.co/api/v1/webhooks \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local Testing",
    "url": "https://abc123.ngrok.io/webhooks/agentref",
    "subscribedEvents": ["conversion.created", "affiliate.joined"]
  }'

Trigger an event

Perform an action that triggers a webhook, such as completing a Stripe test checkout with attribution metadata or approving an affiliate application.

Simulating a Webhook with cURL

To test your endpoint’s signature verification, simulate a delivery:

# Your webhook secret
SECRET="whsec_your_secret_here"

# Build the payload
BODY='{"id":"msg_test_001","type":"conversion.created","schemaVersion":2,"createdAt":"2026-03-23T18:00:00.000Z","merchantId":"mer_test","environment":"development","data":{"id":"conv_test","affiliateId":"aff_test","programId":"prg_test","paymentProvider":"stripe","externalId":"cs_test","saleAmount":9900,"refundedAmount":0,"currency":"usd","status":"pending"}}'

# Generate signature
MSG_ID="msg_test_001"
TIMESTAMP=$(date +%s)
SIGNATURE=$(echo -n "${MSG_ID}.${TIMESTAMP}.${BODY}" | openssl dgst -sha256 -hmac $(echo -n "${SECRET#whsec_}" | base64 -d) -binary | base64)

# Send the request
curl -X POST http://localhost:3000/webhooks/agentref \
  -H "Content-Type: application/json" \
  -H "svix-id: ${MSG_ID}" \
  -H "svix-timestamp: ${TIMESTAMP}" \
  -H "svix-signature: v1,${SIGNATURE}" \
  -d "${BODY}"

Verification Checklist

Before going to production, confirm:

Your endpoint returns 200 within 30 seconds
Signature verification works correctly
You handle duplicate deliveries (check event id)
You process events asynchronously (don’t block the response)
Your endpoint uses HTTPS in production
You’ve subscribed only to events you need
Error handling is in place – a crash won’t take down your server

Debugging Delivery Issues

If webhooks aren’t arriving:

Check the dashboard – go to Settings → Webhooks to see delivery status and errors
Verify the URL – is your endpoint reachable from the public internet?
Check HTTPS – production webhooks require HTTPS (localhost HTTP is allowed in development)
Check event subscription – did you subscribe to the event types you’re expecting?
Check response code – a non-2xx response triggers retries, not immediate re-delivery

Getting Started

Merchant Guide

Agent Integration

Tracking

Integration Guides

Webhooks

For Affiliates

Resources

Testing Locally with ngrok

Simulating a Webhook with cURL

Verification Checklist

Debugging Delivery Issues

​Testing Locally with ngrok

​Simulating a Webhook with cURL

​Verification Checklist

​Debugging Delivery Issues

Testing Locally with ngrok

Simulating a Webhook with cURL

Verification Checklist

Debugging Delivery Issues