Webhooks

Introduction

Our webhook integration allows you to receive real-time notifications about events in your affiliate program. When an event is triggered, we'll send an HTTP POST request to your specified webhook URL with details about the event.

Setting Up Webhooks

To set up a webhook, register your endpoint URL where you'd like to receive event notifications. Ensure your server handles HTTPS requests and is configured to process JSON payloads.

Available Events

You can subscribe to the following events:

• Referral
  • referral.created
  • referral.updated
  • referral.deleted
• Referral Payment
  • referral_payment.created
  • referral_payment.updated
  • referral_payment.deleted
• User
  • user.created
  • user.updated
  • user.deleted
• Program Affiliate
  • program_affiliate.created
  • program_affiliate.updated
  • program_affiliate.deleted

Webhook Payload

When an event is triggered, we'll send a POST request with the following JSON payload:

{
  "event": "event.name",
  "payload": {
    "id": 123,
    "attributes": {
      // Event-specific data
    }
  }
}

• event: The name of the triggered event (e.g., referral.created).
• payload: An object containing the event data.

HTTP Headers

Each webhook request includes the following HTTP headers:

• X-Signature: <signature>
• X-Event: event.name
• Content-Type: application/json

Security and Signature Verification

To ensure the authenticity of the webhook request, you can verify the X-Signature header. The signature is generated using the HMAC algorithm with your webhook secret as the key. You can compare the signature with the computed hash to verify the request's integrity.

Example signature verification in Node.js:

const crypto = require("crypto");
const secret = "your-web-hook-secret";
const signature = req.headers["X-Signature"];
const hash = crypto.createHmac("sha256", secret).update(req.body).digest("hex");

if (signature === hash) {
  // Request is authentic
} else {
  // Request is not authentic
}

Example in Ruby:

require "openssl"

def valid_signature?(payload_body, signature, signature_secret)
  computed_signature = OpenSSL::HMAC.hexdigest('SHA256', signature_secret, payload_body)
  Rack::Utils.secure_compare(computed_signature, signature)
end

Example Request

Request Headers

POST /your/webhook/endpoint HTTP/1.1
Content-Type: application/json
X-Event: referral.created
X-Signature: 4f8b6c...

Request Body

{
  "event": "referral.created",
  "payload": {
    "id": 123,
    "attributes": {
      "referral_code": "REF123",
      "amount": 100.0
    }
  }
}

Retry Policy

If your server doesn't respond with a 2xx status code, we'll retry sending the webhook up to 5 times with an exponential backoff strategy. The retry interval starts at 1 second and doubles with each attempt.

Handling Webhooks

1. Validate the Signature: Verify the X-Signature header to ensure the request is authentic.
2. Process the Event: Parse the JSON payload and handle the event accordingly.
3. Respond with a 2xx Status Code: Respond with a 2xx status code to acknowledge receipt of the webhook. If you respond with an error status code, we'll retry sending the webhook.

Webhook Logs

You can view the logs of webhook delivery attempts in your dashboard. The logs include details about the request, response, and delivery status.

Conclusion

Webhooks provide a convenient way to receive real-time notifications about events in your affiliate program. By integrating webhooks, you can automate workflows and keep your systems in sync with the latest data.

Need Help?

If you have any questions or need assistance with setting up webhooks, feel free to contact our support team at help@sweetref.com.