What is a webhook?
With Webhooks you can send event based information to a customized URL. When an event e.g. QR_CODE_SCANNED occurs, your given URL will be called (webhooked).
How do I create a webhook?
When logged in as an administrator from the White Label Platform, edit a user and go to the Webhooks section. There you can set a destination URL for each event.
What events trigger a webhook?
There are many different events on the platform where a webhook can be triggered.
| Event | Triggered |
|---|
| QR_CODE_CREATED | when a QR Code has been generated |
| QR_CODE_SCANNED | when a QR Code has been scanned |
| VOUCHER_CREATED | when a Voucher has been created |
| VOUCHER_UPDATED | when a Voucher has been updated |
| VOUCHER_REDEEMED | when a Voucher has been redeemed |
| VOUCHER_EXPIRED | when a Voucher has been expired |
| LEAD_CREATED | when a Lead has been created |
| CALL_2_ACTION_BUTTON_CLICKED | when a Call-2-Action Button was clicked |
| JOB_FINISHED | when a bulk designer QR Code process is finished |
What parameters does a webhook send along?
A webhook URL is called depending on the event with certain parameters that are wrapped in a POST request.
Standard parameters
The following parameters are always sent along in a webhook.
| Parameter | Description |
|---|
| event | The name of the event e.g. QR_CODE_SCANNED |
| timestamp | The time when the event occurred |
| user | The user who created the QR Code |
| code | The short URL from the QR Code |
| secrettoken | The secret API key from the user API. You can use this key to verify a webhook request is from your account. |
QR Code was scanned
These parameters are additionally sent along if a QR Code was scanned.
| Parameter | Description |
|---|
| redirects | The number of times a QR Code was scanned |
| visitors | The number of unique visitors who scanned the QR Code |
| device | The device that scanned the QR Code |
| os | The operating system that scanned the QR Code |
| country | The country where the QR Code was scanned |
| lng/lat | An optional location information with a lng/lat pair if a user sends along his GPS data. |
QR Code was updated
These parameters are additionally sent along if the target URL of QR Code is updated.
| Parameter | Description |
|---|
| url | New target URL of the updated QR Code |
uniqevisitors
| Unique visitors
|
redirect
| Number of redirects
|
title
| Title of the QR Code
|
description
| Description field of the QR Code
|
Type
| URL, BUSINESS_CARD, PRODUCT, OPENIMMO, COUPON, PLAIN, LEAD, SOCIAL,TRACING
|
Subtype
| URL, FACEBOOK_PAGE, FACEBOOK_LIKE, INSTAGRAM, SKYPE, APPSTORE, YOUTUBE, TWITTER, LINKEDIN, SMS, EMAIL, TEXT, VCARD, WLAN, GEO, PAYPAL, PINTEREST, EVENT, PHONE, SEPA, MULTI, BITCOIN, VOUCHER, WHATSAPP, PDF, MULTI_LANGUAGE, MP3, MULTI_GEO, MULTI_GEO_CLOSEST, UNLIMITED, UNIQUEIP, UNIQUEID, ONE, GS1
|
| Creation date | QR Code creation date |
Coupon was updated
These parameters are additionally sent along when a voucher has been updated.
| Parameter | Description |
|---|
| title | The title of the voucher |
| description | The description of the voucher |
| The type of voucher |
| type | The type of voucher |
| UNIQUEIP - Voucher can be redeemed once per IP |
| UNIQUEID - Voucher can be redeemed once |
| productname | An optional product name for the voucher |
| website | An optional web page to which the voucher links |
| couponnumber | An optional voucher number that will be displayed on the voucher |
| validfrom | An optional date from when the voucher is valid |
| validto | An optional date from when the voucher expires |
Voucher was redeemed
| Parameter | Description | |
|---|
| status | Status of redemption: | |
| SUCCESS | Voucher was redeemed |
| VOUCHER_ALREADY_REDEEMED | Voucher was already redeemed before |
| VOUCHER_EXPIRED | Voucher has expired |
| QUOTA_EXCEEDED | The limit of redemptions was exceeded |
| type | The voucher type: | |
| UNIQUEIP | Voucher can be redeemed once per IP |
| UNIQUEID | Voucher can be redeemed once |
| eancode | | If the voucher is redeemed and an EAN barcode is set, the EAN code will be transmitted in the webhook. |
| uniqueid | | If the QR Code is a one-time redeemable voucher, the unique ID of the voucher is returned. This is one of the unique IDs when you create bulk QR Codes for a uniquely redeemable voucher. |
New lead
These parameters are additionally sent when a new lead is generated.
| Parameter | Description |
|---|
| email | The email address of the new lead |
| name | The name of the new lead |
| Parameter | Description |
|---|
| c2a | The URL of the Call-2-Action button Lorem |
Job was finished
This parameter is additionally sent along when a job that provides designer QR Codes for download is finished with the calculation.
| Parameter | Description |
|---|
| download | A link to download the job result that is valid for 30 days |
Webhook logs
You can check the logs from your user settings to see which webhooks, when have been fired and if there has been any error.
Debugging
If you want to output the information sent to your server on a webhook, use the following PHP script to display all parameters:
<?php
// Test WebHook and show parameters
error_log("Fired WebHook");
// Post Parameter
foreach ($_POST as $param_name => $param_val) {
error_log("$param_name: $param_val");
}
// Get Parameter
foreach ($_GET as $param_name => $param_val) {
error_log("$param_name: $param_val");
}
// if JSON submitted
$json = json_decode(file_get_contents('php://input'));Test a webhook online
With the free webhook.site service you can immediately test a webhook online.
Copy a webhook setup to another user profile
The Administrator API allows you to copy a webhook setup from one user profile to another.