Marketing Integration Webhooks


Introduction

"Marketing Integration Webhooks" from Wash-Dry-Fold POS allows external marketing software to receive updates when certain status changes occur to a laundry order, or when a customer profile is created or updated. This way you do not need to poll our database for updates, but can instead receive and react to them in real time as they happen and trigger automated workflows in external marketing software.


TECHNICAL STUFF AHEAD!

  • To use the Marketing Integration Webhooks feature, you'll need to be familiar with sending HTTP requests, APIs, and reading API documentation.
  • Our support team is able to provide basic support for this feature, but they cannot troubleshoot the external marketing software you use.
  • We strongly recommend speaking with our good friends at LaundroBOOST or Suds Digital for assistance with setting up automations for your laundromat's marketing!

How to Create a Marketing Integration Webhook

To start receiving webhooks, follow these steps:

  1. Click the gear icon in the top right corner
  2. Click on Account Settings and enter your admin/manager password
  3. Go to the Webhooks section
  4. Enter a name for the webhook, select an event you want to subscribe to, and provide the URL for external software where you wish the webhook updates to be sent (such as Zapier or ActiveCampaign, for example) and press Save

A picture showing how to access the Webhooks feature on the Account Settings page within Wash-Dry-Fold POS


List of events you can subscribe to with a webhook:

customer.created
customer.updated
order.created
order.started
order.completed
order.returned

The event name is sent in the header as X-Webhook-Event. It is also sent in the body as Webhook_Event.

ONLY WORKS FOR ORDERS TREATED AS "LAUNDRY SERVICE"

The "order" referred to in these webhook events are exclusively "laundry service" orders, meaning they are the same ones that populate the Order Tracker screen in Wash-Dry-Fold POS. They contain at least one line item that has the "laundry service" option enabled in the Item settings on the Inventory page.

An image showing where to set the Laundry Service item type for an item in the Inventory page of Wash-Dry-Fold POS. Only Laundry Service type orders will have their order status notifications sent via webhook events.

Webhook Status

Active means that the webhook is live and will send payloads to the Webhook URL

Paused means that the webhook will not send payloads

Disabled means that the webhook will not send payloads and that there is an issue with the Webhook URL or it has received an error from the destination URL more than 5 times in a row when attempting to send a payload. After correcting the error, change the status back to Active and press Save to enable sending a payload again.

An example image of an invalid Webhook URL

Webhook Security (Optional)

You can verify the authenticity of webhook events sent by WDF POS using the X-Webhook-Signature and X-Webhook-Timestamp headers included in each event.

WDF POS generates signatures using HMAC with SHA-256. The signature is generated using a signing secret that is attached to the webhook you have created. The signing secret is automatically generated when you create a new webhook. You can view it by clicking Edit.

It is obscured from view in this example image but you would get it from this input titled “Signing Secret”.

Example image of where to find the Signing Secret for your webhook

Warning! Treat your external marketing software's webhook URL address and your Signing Secret as sensitive data. Do not share them publicly!

Verification

To verify the authenticity of a webhook request, you need to generate the expected signature on your side and compare it to the one provided by WDF POS in the X-Webhook-Signature header. Here are the steps to do that.

Step 1: Extract the timestamp

The timestamp is found in the X-Webhook-Timestamp header.

Step 2: Create the expected signature

To create the expected signature, first you need to construct the payload that needs to be signed. The payload string is created by concatenating the following values:

  • The timestamp (timestamp value sent in X-Webhook-Signature)
  • The character .
  • JSON payload of the request body (data sent by WDF POS for a specific event)

Now compute an HMAC of the payload using SHA-256 as the hash function and the signing secret as the key.

Step 3: Compare signatures

Compare the X-Webhook-Signature in the header to the expected signature you constructed and make sure they match exactly.

For additional security, validate that the timestamp in X-Webhook-Timestamp is no more than 5 minutes old to prevent replay attacks. When comparing the computed signature against the received signature, always use a constant-time comparison function to protect against timing attacks.



Troubleshooting Marketing Integration Webhooks

On the Webhooks section of the Account Settings page, we provide a log of the 5 most recent webhooks sent from your Wash-Dry-Fold POS software. You can click on the arrow next to each record to expand the entry and see exactly what data was sent out and where it was sent.

An example image of the Webhook Log of the 5 most recent webhook event messages sent from your Wash-Dry-Fold POS account
Example image of the Webhook Log