Skip to main content
Each webhook watches one event on one resource and delivers it to a URL you choose. The Webhooks screen lists your webhooks and shows whether each one is active.

​
Where to find it

In the admin, click the Settings gear in the top bar. In the Settings sidebar, under System, select Webhooks. You can also click the Developer Hub code icon in the top bar, then select Webhooks in the Developer Hub sidebar.

​
The webhooks list

Click Create Webhook at the top of the screen to add a webhook. To see deliveries, click View Webhook Logs in the banner below the page title. Webhook Logs shows each delivery’s status and response code, and lets you retrigger events that failed.
  • The All, Active and Inactive tabs filter the list by status.
  • Use the search box above the list to find a webhook by its URL, resource or event.
The list has these columns:
  • Resource: the kind of record the webhook watches, such as Order or Product.
  • Event: the change that triggers a delivery, such as Created or Updated.
  • URL: the address that receives the events.
  • Status: Active or Inactive. Fluid sends events only to active webhooks.
Click a row to open the webhook. Each row’s three-dot menu has Edit and Delete.
To create, open, edit or delete webhooks, your role needs Full access to Developer, or its Manage webhooks and API configuration switch turned on. With View only, you can see the list but not change it. See Roles.

​
The webhook panel

Create Webhook opens a side panel with these fields. Opening an existing webhook shows the same fields in the Edit Webhook panel.
  • Resource: the kind of record to watch. Required.
  • Event: the change that triggers a delivery. The list fills in after you choose a Resource. Required.
  • Destination URL: the address that receives the events. Required. The URL must use HTTPS and can’t point to a private or internal address. You can register a URL only once for the same event.
  • HTTP Method: the request method Fluid uses for each delivery. Choose POST (the default) or PUT, whichever your endpoint expects. The list also shows PATCH and DELETE, but Fluid doesn’t accept them, so the webhook isn’t saved. See Why do I see both an error and a success message?
  • Authentication Token (optional): a secret your endpoint expects. Fluid sends it with each delivery and uses it to sign the delivery, so your endpoint can check that the request came from Fluid. If you create the secret yourself, make it long and random. See Verify a delivery.
  • Timeout (seconds): Fluid doesn’t save this value, so you can leave it blank.
  • Active: whether the webhook receives events. It’s on by default for a new webhook.
If Resource, Event or Destination URL is empty when you click Save, the admin asks you to fill in all required fields.

​
Create a webhook

1

Open the panel

On the Webhooks screen, click Create Webhook.
2

Choose what to watch

Choose a Resource, then an Event.
3

Enter the destination

Enter the Destination URL. If your endpoint expects PUT, change HTTP Method to PUT. If your endpoint checks deliveries, enter the secret it uses in Authentication Token (optional).
4

Save

Leave Active on so the webhook starts receiving events, then click Save. To check that it’s listed, search for its URL in the search box.

​
Edit a webhook

1

Open the webhook

Click the webhook’s row, or choose Edit from its three-dot menu. The Edit Webhook panel opens.
2

Make your changes

Change the Destination URL, HTTP Method, Authentication Token (optional) or Active setting.
3

Save

Click Save. To confirm your change, search for the webhook’s URL, or open the webhook again.
  • The admin doesn’t save changes to Resource or Event. To send a different event to the same URL, create a new webhook, then delete the old one if you no longer need it.
  • Clearing Authentication Token (optional) doesn’t remove a token that’s already saved. To remove it, delete the webhook, then create it again without a token.
  • If a webhook was set to GET through the API, saving it here changes it to POST.

​
Pause or resume a webhook

1

Open the webhook

Click the webhook’s row, or choose Edit from its three-dot menu.
2

Turn Active off or on

Turn Active off to stop deliveries, or on to start them again.
3

Save

Click Save. The webhook’s Status changes to Inactive or Active.
Turning a webhook back on doesn’t resend events it missed while it was off.

​
Delete a webhook

Delete has no confirmation step, and you can’t undo it. To stop deliveries for now, turn off Active instead.
In the list, choose Delete from the webhook’s three-dot menu. Check that the webhook is gone from the list.

​
FAQ

If you see an error message after you click Save or Delete, the change didn’t go through, even if a success message also appears. After Save, the panel closes either way, so click Create Webhook or open the webhook again and re-enter your values. Fix the problem, then save again.
Fluid queues deliveries. They usually arrive in near real time, but can lag 5 to 10 minutes when the queue is backed up.
No. Fluid doesn’t resend a failed delivery on its own. To resend one yourself, open Webhook Logs, find the event on the All tab by its red Failed badge, and click Retrigger in its details. See Retrigger a failed event. Retrigger sends the event again to every active webhook for that event, not only the one that failed.Deliveries that got no response from your endpoint, such as a timeout, show as Pending in Webhook Logs and can’t be resent.
Each delivery is a JSON request. For the payload format, see Register and handle webhooks.
  • Settings: find the other screens under Company, Commerce, Payments and System.
  • Webhook Logs: check each delivery and retrigger events that failed.
  • Callbacks: have Fluid call your endpoint during store events, such as cart tax calculation.
  • Roles: set the permissions this screen needs.
  • Register and handle webhooks: the delivery format and how to verify a delivery.