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:

Example in Ruby:

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

Validate the Signature: Verify the X-Signature header to ensure the request is authentic.

Process the Event: Parse the JSON payload and handle the event accordingly.

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.

Introduction#

Setting Up Webhooks#

Available Events#

Webhook Payload#

HTTP Headers#

Example Request#

Request Headers#

Request Body#

Retry Policy#

Handling Webhooks#

Webhook Logs#

Conclusion#

Need Help?#