An introduction to webhooks

A Mechanic webhook allows you to submit your own data, resulting in a new event having a particular topic, containing the data you've submitted. Webhooks are called with simple HTTP POST requests, which means they can be called from any programming language, and from many applications.

To learn how to create a webhook, see Getting started with webhooks


A Mechanic webhook is configured with a specific event topic. When you create the webhook, Mechanic will generate a unique URL, just for that webhook. Any valid POST request to that webhook URL will result in a new event being created, having the topic you've configured for that webhook, containing the parsed data from your POST request.

Any request using an HTTP method other than POST will receive a 405 Method Not Allowed response.


The Mechanic webhook URL accepts these common request content types:

  • text/plain
  • application/json
  • application/x-www-form-urlencoded

When called in-browser via JavaScript, one must be respectful of CORS origins. Mechanic will automatically configure your webhook URL for CORS submissions from your Shopify store's subdomain, and from the custom domain name configured for your store (if applicable). To add additional approved CORS origins, configure the "Additional webhook CORS origins" section of your Mechanic account settings.


A successful webhook request will always receive a 204 No Content response, indicating that an event has been created with the submitted data. The event will be run asynchronously, along with any generated task and action runs that follow.

Retrieving run results

The webhook ingress API is solely for ingesting data to form a new event. Because of this, the webhook response necessarily does not contain any data resulting from the runs that might follow. (To further explain the point: there could be zero task runs that follow, or many, and there are no hard guarantees for when those runs would finish.)

This means that the caller must use another avenue for retrieving the results of any generated runs. In general, there are three options for this:

  • For a consistently re-occurring call with a single caller, the task responding to the webhook event may write its results to the Mechanic cache, allowing the caller to retrieve results using a cache endpoint. For more on this, see Using cache endpoints to share data.
  • For calls with variable or multiple callers, consider generating a UUID, and submitting it to the webhook along with the other submitted data. Tasks responding to the webhook event should store their results keyed by that UUID, using an external storage mechanism (possibly via the "http" or "ftp" actions).
  • For calls triggered by customer activity on an online Shopify storefront, consider (a) requiring the customer to be logged in, (b) sending the customer ID in the webhook request data, (c) storing task results in a customer metafield (using the "shopify" action), and (d) using storefront Liquid to render the content of that metafield, polling until a value is present.


With cURL:

curl -X POST -F foo=bar
curl -X POST -H "content-type: application/json" -d @data.json

With jQuery:

$.post('', { foo: 'bar' });
  url: '',
  method: 'POST',
  data: { foo: 'bar' }
let data = { foo: 'bar' };

  url: '',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  data: JSON.stringify(data)
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.