Webhooks allow 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. Within 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
Smartwaiver also offers Webhook Queues, which are accessible through the V4 API. When a new waiver is signed, an item will be added to the queue and kept for seven days. You can retrieve and delete items from the queue at your leisure without having to maintain a public webhook endpoint.
For more details and to see all the available routes, visit our API Documentation.
HTTP POST Request
Two 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).
-
“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).
Important: API Keys are different than the Webhook Private Key.
Retries
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
Webhook Logs
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.
For example:
Instead of using: https://www.example.com/webhook/
Use: https://www.example.com/webhook/?customer_id=1234
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:
https://www.smartwaiver.com/api/ip.xml
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
You can add up to three webhooks at your account-level (i.e. for all of your waivers).
To add a webhook to your account:
- Click My Account (from the gray lefthand sidebar).
- Click the Webhooks tab/link (top middle).
- Click the green button to Enable Account Level Webhooks.
- Add your webhook URL > adjust the settings options as desired > and click the green Save button.
(These settings will apply to any additional webhooks that are added.) - If you have a 2nd account level webhook, click the blue Add Webhook button to populate an additional URL field.
- Add your 2nd webhook URL > and click the green Save button.
- If you have a 3rd account level webhook, click the blue Add Webhook button one more time to populate the final URL field.
- Add your 3rd webhook URL > and click the green Save button.
Each account supports up to three webhooks at this level.
Once you have clicked the 'Add Webhook' button to populate all three account webhook URL fields, the button will turn gray. (Shown below)
Related Articles:
