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

Configuration

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.

Requests

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 myshopify.com 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.

Responses

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 response necessarily does not contain any data resulting from the runs that follow. 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

Examples

With cURL:

curl -X POST -F foo=bar https://usemechanic.com/webhook/abcdef12-3456-abcd-ef12-3456abcdef12
curl -X POST -H "content-type: application/json" -d @data.json https://usemechanic.com/webhook/abcdef12-3456-abcd-ef12-3456abcdef12

With jQuery:

$.post('https://usemechanic.com/webhook/abcdef12-3456-abcd-ef12-3456abcdef12', { foo: 'bar' });
$.ajax({
  url: 'https://usemechanic.com/webhook/abcdef12-3456-abcd-ef12-3456abcdef12',
  method: 'POST',
  data: { foo: 'bar' }
});
let data = { foo: 'bar' };

$.ajax({
  url: 'https://usemechanic.com/webhook/abcdef12-3456-abcd-ef12-3456abcdef12',
  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.