Overview

SPRL Webhooks allow you to automatically send activity from your SPRL links and QR Codes to your own application.

Instead of repeatedly checking SPRL for new activity, you can provide an HTTPS webhook URL and SPRL will send a request to your application whenever the configured trigger occurs.

Webhooks are useful for connecting SPRL with your CRM, internal application, automation platform, reporting system, or other backend services.

Webhooks work while Click Tracking is active. If Click Tracking is disabled, webhook events are automatically disabled.

How Webhooks Work

1. Go to Dashboard → Settings → Webhooks.
2. Click Add Webhook.
3. Enter the HTTPS URL where SPRL should send activity.
4. Select the event trigger.
5. If required, configure one or more trigger values.
6. Optionally configure a delivery limit.
7. Optionally add custom key/value data.
8. Save the webhook.
9. Use Test Webhook to verify your endpoint.

Once configured, SPRL automatically sends webhook requests when the selected trigger conditions are satisfied.

Supported Triggers

Create a Webhook

To create a webhook:

1. Go to Dashboard → Settings → Webhooks.
2. Click Add Webhook.
3. Enter a descriptive webhook name.
4. Enter your application's HTTPS webhook URL.
5. Select the required trigger.
6. Configure trigger values when required.
7. Optionally configure a delivery limit.
8. Optionally add custom key/value data.
9. Click Save Webhook.

The webhook URL must use HTTPS.

Trigger Values

Country, city, device, platform, and referrer triggers support multiple values.

For example, a country trigger can contain:

IN
US
GB

The webhook is triggered when the activity matches any of the configured values.

Delivery Limit

A delivery limit can optionally be configured for each webhook.

This allows you to limit how many webhook deliveries can be generated by that webhook configuration.

The delivery limit is optional. If no limit is configured, the webhook has no configured delivery limit.

Example:

Delivery Limit: 1000

Custom Data

You can optionally add your own custom key/value data to a webhook configuration. This allows your application to identify the campaign, source, integration, or other internal reference.

Example:

{ "campaign": "summer-sale", "source": "facebook", "customer_type": "premium"
}

Custom values must be simple text or scalar values.

SPRL reserves certain keys for webhook activity data. The following keys cannot be used as custom keys:

event
url_slug
timestamp
trigger
visitor
ip
country
city
device
platform
referrer

Webhook Request

When a configured trigger occurs, SPRL sends an HTTP POST request to your webhook URL.

Your endpoint should accept JSON POST requests over HTTPS.

Webhook Payload

The webhook payload contains the activity information associated with the event.

The standard webhook fields are:

If custom data has been configured, the custom values are also included in the webhook payload.

Example Webhook Payload

{ "event": "click", "url_slug": "abc123", "timestamp": 1755000000, "trigger": "every_click", "visitor": "visitor_123", "ip": "203.0.113.10", "country": "IN", "city": "Bengaluru", "device": "mobile", "platform": "android", "referrer": "google.com", "campaign": "summer-sale", "source": "facebook"
}

The actual values depend on the activity that triggered the webhook. Some fields may be unavailable for certain requests and can therefore be empty or null.

Webhook Security

Every webhook configuration has a unique Signing Secret. SPRL uses this secret to generate a signature for webhook requests.

Your application can use the signature to verify that the request was generated by SPRL and that the request body has not been modified.

Signing Secret

When a new webhook is created, SPRL automatically generates a unique signing secret.

The signing secret can be viewed and copied from the webhook configuration. Store it securely in your application.

Editing a webhook does not require generating a new secret.

Webhook Signature

SPRL sends the webhook signature using the X-SPRL-Signature HTTP header.

Generate the HMAC SHA256 signature using the raw request body and the webhook signing secret.

signature = HMAC-SHA256( request_body, webhook_secret
)

Compare the generated signature with the X-SPRL-Signature header.

Only process the webhook when the signatures match.

Test Webhook

SPRL provides a Test Webhook option so you can verify your endpoint before processing real activity.

1. Go to Dashboard → Settings → Webhooks.
2. Find the webhook you want to test.
3. Click the Test button.
4. SPRL sends a test POST request to the configured URL.
5. Check your application logs to confirm that the request was received.

A test request does not represent a real click or QR scan.

Webhook Response

After receiving a webhook request, your application should return a successful HTTP response to confirm that the request was received.

SPRL considers a webhook delivery successful when your endpoint returns an HTTP 2xx status code.

Your application does not need to return a specific JSON response. SPRL primarily uses the HTTP response status to determine whether the webhook was successfully received.

For example, the simplest successful response is:

HTTP/1.1 200 OK

A JSON response is also acceptable:

{ "status": true
}

The response body is not required for successful webhook delivery.

Failed Webhook Delivery

A webhook delivery is considered unsuccessful when your endpoint returns a non-2xx HTTP response, cannot be reached, or does not respond within the configured request timeout.

Webhook Delivery & Retries

SPRL processes webhook deliveries asynchronously so webhook requests do not affect link redirection or tracking performance.

• Webhooks are processed asynchronously after the event is recorded.
• If your endpoint does not respond successfully, SPRL automatically retries the webhook delivery.
• SPRL makes up to 3 delivery attempts.
• Retry intervals are approximately 30 seconds and 2 minutes.
• A webhook is marked as Delivered when your endpoint returns a successful HTTP 2xx response.
• If all delivery attempts fail, the webhook event is marked as Failed.

Webhook Status

A webhook can only deliver activity while it is active and Click Tracking is enabled.

Managing Webhooks

You can manage your webhook configurations from:

Dashboard → Settings → Webhooks

• Add: Create a new webhook.
• Edit: Update the webhook configuration.
• Test: Send a test request to your webhook URL.
• Signing Secret: View and copy the webhook signing secret.
• Delete: Remove the webhook from your active configurations.

Common Issues

Best Practices

• Always use an HTTPS endpoint.
• Keep your signing secret secure.
• Verify the X-SPRL-Signature header before processing the request.
• Return an HTTP 2xx response after successfully receiving the webhook.
• Keep your webhook endpoint available and responsive.
• Use descriptive webhook names.
• Configure only the triggers your application actually needs.

Frequently Asked Questions

What are SPRL Webhooks?

SPRL Webhooks allow SPRL to automatically send supported link and QR activity to an HTTPS endpoint provided by your application.

Do I need an API key for Webhooks?

No. Webhooks use a webhook-specific signing secret to verify requests.

Can I configure multiple countries or cities?

Yes. Country, city, device, platform, and referrer triggers can contain multiple values. The webhook is triggered when activity matches any configured value.

Can I create multiple webhooks?

Yes. You can create multiple webhook configurations with different URLs, triggers, and settings.

Can I add custom data?

Yes. You can add custom key/value data to a webhook configuration.

Can I test a webhook?

Yes. Use the Test option from the Webhooks settings page to send a test request to your configured endpoint.

What should my application return?

Your application should return an HTTP 2xx response after successfully receiving the webhook. No specific JSON response body is required.

What happens when Click Tracking is disabled?

Webhook events are automatically disabled while Click Tracking is inactive.

Can I edit an existing webhook?

Yes. You can edit the webhook configuration without generating a new signing secret.

How do I verify that a webhook came from SPRL?

Use the X-SPRL-Signature header and your webhook signing secret to calculate and verify the HMAC SHA256 signature.