Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentref.co/docs/llms.txt

Use this file to discover all available pages before exploring further.

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:
1

Start your local server

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

Start ngrok

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

Register the webhook

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"]
  }'
4

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