Webhooks allows your script to import your waiver’s raw data and PDF files in near real-time by providing a URL to a script on your server. Up to 10 seconds after a signed waiver is submitted, we’ll send an HTTP POST Request to the URL you’ve specified.
- Set your Webhook URL at: Webhook Config
HTTP POST Request
Three keys are passed:
“unique_id” is the new waiver’s id. The value of “unique_id” can be used to call the API using query option “rest_waiverid”. This will allow you to obtain the complete waiver’s information (including full name, date of birth and the credentials needed to download the PDF to your server).
“credential” is an optional value which allows you to verify if the HTTP POST Request originated from Smartwaiver (as opposed to a hacker or bot). See Securing Webhooks below.
“event” describes what prompted the webhook. For now this is exclusively “new-waiver” but this allows us to expand the purpose of webhooks in the future. It would be wise (in preparation for future expansion) to write your script to ignore events other than “new-waiver” for now).
Responding to a webhook
The endpoint should acknowledge the receipt of a webhook by returning a 2xx HTTP status code. Any other information returned in the request headers or request body is logged but will be ignored. All response codes outside this range (3xx, 4xx, 5xx), will indicate that you did not receive the webhook and the webhook will go into retry mode.
Why the HTTP POST Request Does Not Include More Information
To make development easier, we allow both HTTP and HTTPS Webhook URLs. If you use an HTTP URL, the communication to your server is not secure.
Therefore, it isn’t wise to include personal information. All the information can be securely accessed by calling our API (which exclusively uses HTTPS).
If available, always use an HTTPS url (so you can have security by using an SSL-enabled URL).
Regardless, to verify that the HTTP POST Request came from Smartwaiver.com check the that value of POST key “credential” is equivalent to:
MD5(YOUR_WEBHOOK_PRIVATE_KEY + UNIQUE_ID)
(“+” is string concatenation)
To determine your webhook private key (it is only visible after you setup a webhook url) go to: Webhook Private Key
UNIQUE_ID is included in the HTTP POST Request.
If “credential” is not set or not equivalent to the MD5 value above, the HTTP POST Request did not come from Smartwaiver and should be ignored.
md5(<Waiver UniqId>|<Webhook Endpoint>)
Waiver UniqId = 'a1b2c3'
Endpoint = 'http://www.example.com/webhook'
Important: API Keys are different than the Webhook Private Key.
If the HTTP POST Request fails or takes too long to connect (timeout of 5 seconds), Smartwaiver will try again every 5 minutes. If it fails five times that individual webhook will be canceled and a log will be created ([view log]) but future waiver’s webhooks will continue like normal.
If more than 50 webhooks fail in a row, webhooks will be disabled for your account and an email will be sent to the owner of the Smartwaiver account. You will be able to re-enable webhooks by logging in and resetting your Webhook URL.
Specify When Webhooks Fire
Waivers signed at a Smartwaiver Kiosk fire shortly after the waiver is submitted. Waivers signed and submitted remotely can fire either directly after being submitted or after the participant validates their email address. Select which option works best for you at: Webhook Config
To monitor when waivers are created and when Webhooks are firing you can view the Logs from your Webhook Config page. Simply click on the 'Show Webhook Logs' button. You will see:
- The Unique ID
- The Webhook URL
- The status of the Webhook
- Date the waiver was completed
- The difference in time when the waiver was completed and the Webhook fired
Using Webhooks to Integrate Multiple Customers Into the Same Web App
If you need to know which of your customers have set up Webhooks, we recommend customizing their Webhook URL so it passes their customer ID.
Instead of using: https://www.example.com/webhook/
and replace "1234" with their Customer ID.
IP Addresses (Optional)
If you'd like a list of IP addresses, Smartwaiver will initiate Webhooks by importing the following XML file:
If we require multiple IP addresses in the future we'll add them to this XML file 24 hours before Webhooks start being initialized from your IP so it's a good idea to automatically import the list every night if you are using it to filter what IPs may call your script.
How it Flows
How do I use Webhooks for specific waivers?