Webhooks
A Mechanic webhook allows data to be submitted directly to Mechanic, resulting in a new event having a particular topic, containing the submitted data. Webhooks are called with simple HTTP POST requests, which means they can be called from any programming language, and from many applications.
Mechanic's webhook API includes CORS support for all origins, making these requests available for use in online user experiences.
This article is an introduction to webhooks. To get started quickly, see Creating a Mechanic webhook.
- Name — Something to remember this webhook by ✨
- Event data mode — Either "Auto" or "Full request"; see below
- Webhook URL — A unique, permanent, webhook-specific URL, supplied by Mechanic after creating the webhook
Each webhook has a choice of modes used to translate request data into event data.
Changing a webhook's event data mode takes effect immediately for all incoming requests. It does not apply retroactively, i.e. it has no impact on webhook events that were received prior to the change.
In "Auto" mode, event data is the result of merging an interpreted hash of parameters from the request body with an interpreted hash of parameters from the request query string.
If no parameters from the request body are found, or if parsing the request body fails for any reason, event data is set to parameters from the request query string.
If no structured parameters are found from either the request body or the request query string, event data is set to the request body in string form. If the string is blank (i.e. zero-length or consisting only of whitespace), event data is set to
null.In "Full request" mode, event data is set to a hash with the following keys:
Key | Type | Notes |
|---|---|---|
body_base64 | Base64-encoded string | The raw request body, encoded in base64 |
body | Hash or null | The interpreted set of structured parameters from the request body, or null if parsing fails for any reason |
client_ip | String | The IP address of the requesting client |
headers | Hash | Represents the request headers, keyed by lowercased header names, containing arrays of string values (⚠️ see warning below) |
mime_type | String or null | The MIME type of the request as interpreted from the content-type request header, or null if that header was not found |
query_string | String or null | Contains everything after the "?" character in the request URL, or null if no such value was found |
query | Hash or null | Contains the interpreted set of structured parameters from the query string, or null if none were found |
request_id | UUID string | Uniquely identifies the request, having the same value found in the original webhook request response in the x-request-id header |
webhook_id | UUID string | Identifies the Mechanic webhook which handled the request |
{% assign raw_request_body = event.data.body_base64 | decode_base64 %}
Mechanic's webhook request header representation has an important limitation: the array of header values is currently limited to a size of one (1). If multiple request headers are given using the same header name, their values will be concatenated with commas and represented in a single string, as the sole array element.
This means that a request which defines both
X-Foo: Bar and X-Foo: Baz headers will be represented thusly:"headers": {
"x-foo": [
"Bar,Baz"
]
}
Let us first acknowledge that this is ridiculous. 💯 ✅
As of this writing (2023-03-08), an upstream provider of Mechanic's does not have proper support for requests containing repeated header names. Mechanic's behavior here is a compromise chosen (1) to allow us to resolve this in the future without requiring a change to the format of this representation, and (2) for consistency with HTTP action's response format.
When this issue is resolved, the header example above will be represented as follows:
"headers": {
"x-foo": [
"Bar",
"Baz"
]
}
Task code that reads webhook request headers should take these two possible representations into account.
Sample "Full request" event data
{
"body_base64": "LS0tLS0[...]S0NCg==",
"body": {
"file_upload": {
"content_base64": "iVBORw0[...]K5CYII=",
"mime_type": "image/png",
"name": "tiny.png",
"size": 1265
},
"key": "value",
"hash": {
"key": "hash_value"
},
"array": [
"array_value"
]
},
"client_ip": "8.8.8.8",
"headers": {
"content-length": [
"1759"
],
"content-type": [
"multipart/form-data; boundary=----WebKitFormBoundaryqcjvhXaEdqng2TkC"
],
"x-custom": [
"Value"
],
"x-foo": [
"Bar,Baz"
]
},
"mime_type": "multipart/form-data",
"query_string": "key=value&hash[key]=hash_value&array[]=array_value",
"query": {
"key": "value",
"hash": {
"key": "hash_value"
},
"array": [
"array_value"
]
},
"request_id": "a8723f25-20ff-4b89-a46c-73fc387a16d3",
"webhook_id": "d166806f-1f79-4283-b4b4-80a38ee04431"
}
The Mechanic webhook API only accepts POST requests. (All other methods will receive a 405 Method Not Allowed response.)
Mechanic's webhook API includes CORS support for all origins, making these requests available for use in online user experiences.
File uploads are supported via multipart/form-data webhook requests. Each uploaded file will be represented in event data (regardless of event data mode) as a structured hash having the following keys:
content_base64— A base64 string representation of the file contentmime_type— The MIME type of the file, as declared in the headers for that filename— The original name of the file, as declared in the headers for that filesize— An integer reflecting the size of the file in bytes
{% assign file = event.data.body.my_upload %}
{% assign raw_file_content = file.content_base64 | decode_base64 %}
File upload sample representation
{
"my_upload": {
"content_base64": "PD94bWw[...]mc+Cg==",
"mime_type": "image/svg+xml",
"name": "logo.svg",
"size": 12345
}
}
When configuring an integration with external apps and services, some require specific behavior from webhook hosts – usually for the purposes of validating a webhook before it's enabled. Mechanic includes specific support for some known webhook clients; request new ones at mechanic.canny.io.
A webhook invocation signals its client selection via a path suffix. Given a webhook URL of
webhooks.mechanic.dev/0000..0000, a client-specific endpoint for Ship24 (for example) would be available at webhooks.mechanic.dev/0000..0000/ship24.With cURL:
curl -X POST -F foo=bar https://webhooks.mechanic.dev/abcdef12-3456-abcd-ef12-3456abcdef12
curl -X POST -H "content-type: application/json" -d @data.json https://webhooks.mechanic.dev/abcdef12-3456-abcd-ef12-3456abcdef12
With fetch:
const data = {
some_data: 'yep here it is',
};
fetch(
'https://webhooks.mechanic.dev/0000-0000',
{
method: 'post',
body: JSON.stringify(data),
headers: {
'content-type': 'application/json'
},
}
).then(console.log);
With jQuery:
$.post('https://webhooks.mechanic.dev/0000-0000', { foo: 'bar' });
$.ajax({
url: 'https://webhooks.mechanic.dev/0000-0000',
method: 'POST',
data: { foo: 'bar' }
});
let data = { foo: 'bar' };
$.ajax({
url: 'https://webhooks.mechanic.dev/0000-0000',
method: 'POST',
headers: {
'content-type': 'application/json'
},
data: JSON.stringify(data)
});
A properly-formatted webhook request will always receive a 204 No Content response, even in the case of an incorrect webhook ID in the URL.
If an active webhook ID was used, then an event will be created with the submitted data. The event will be run asynchronously, along with any generated task and action runs that follow.
All POST requests to webhooks.mechanic.dev will receive an
x-request-id response header, containing a UUID. This ID can be used as a search term when looking up a Mechanic event, and can be referenced in Liquid as a part of the Event object via event.webhook_request_id. 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 calls with variable or multiple callers, use the webhook request ID by reading the
x-request-idresponse header in your client code, and by referencingevent.webhook_request_idin your task's Liquid code in. 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.
Last modified 2mo ago