Webhooks

4 Minutes

01/24/2023

What is a webhook?
How do I create a webhook?
What events trigger a webhook?
What parameters does a webhook send along?
Webhook logs
Debugging
Test a webhook online
Copy a webhook setup to another user profile

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).

Webhooks are only available with our White Label plan.

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
accuracy	Scan-accuracy in meters.
anonymizedip	Anonymized IP address of the scanning device.
code	The QR Code's Short URL.
country	The country where the QR Code was scanned.
device	The device that scanned the QR Code.
email	Your account's e-mail address.
event	QR_CODE_SCANNED
lng/lat	An optional location information with a lng/lat pair if a user sends along his GPS data.
mobile	Scanner device type.
os	The operating system that scanned the QR Code.
querystring	When query URL parameters are added to the short URL of a QR Code they are added to the payload.
redirects	The number of times a QR Code was scanned.
secrettoken	Your account's Secret API Key.
timestamp	The exact date and time the scan occured.
type	QR Code/Landing Page type (URL = code QR dynamique, BUSINESS_CARD, PRODUCT, OPENIMMO, COUPON, PLAIN, LEAD, SOCIAL,TRACING).
uniqueid	Unique ID of this specific scan.
user	Your account's user name.
visitors	The number of unique visitors who scanned the QR Code.

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

These parameters are additionally sent when a voucher has been 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

C2A-button was clicked

This parameter is also sent when a Call-2-Action button is clicked.

Parameter	Description
c2a	The URL of the Call-2-Action button

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.