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.

Configuration

A Mechanic webhook is configured with a name and a specific event topic, and is assigned a unique, webhook-specific URL. Any valid POST request to the assigned webhook URL will result in a new event being created, having the configured topic, containing the parsed data from the POST request.

Requests

The Mechanic webhook API only accepts POST requests. (All other methods will receive a 405 Method Not Allowed response.)
The following content types are supported, and will be parsed appropriately as event data:
  • text/plain
  • application/json
  • application/x-www-form-urlencoded
Mechanic's webhook API includes CORS support for all origins, making these requests available for use in online user experiences.

Client-specific endpoints

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 usemechanic.com/webhook/0000..0000, a client-specific endpoint for Ship24 (for example) would be available at usemechanic.com/webhook/0000..0000/ship24.
Client
Webhook suffix
Behavior notes
​
Asana
asana
Supports the X-Hook-Secret header for the handshake phase
​Docs​
Ship24
ship24
Supports HEAD requests for webhook verification
​Docs​

Examples

With cURL:
1
curl -X POST -F foo=bar https://usemechanic.com/webhook/abcdef12-3456-abcd-ef12-3456abcdef12
Copied!
1
curl -X POST -H "content-type: application/json" -d @data.json https://usemechanic.com/webhook/abcdef12-3456-abcd-ef12-3456abcdef12
Copied!
With fetch:
1
const data = {
2
some_data: 'yep here it is',
3
};
4
​
5
fetch(
6
'https://usemechanic.com/webhook/0000-0000',
7
{
8
method: 'post',
9
body: JSON.stringify(data),
10
headers: {
11
'content-type': 'application/json'
12
},
13
}
14
).then(console.log);
Copied!
With jQuery:
1
$.post('https://usemechanic.com/webhook/0000-0000', { foo: 'bar' });
Copied!
1
$.ajax({
2
url: 'https://usemechanic.com/webhook/0000-0000',
3
method: 'POST',
4
data: { foo: 'bar' }
5
});
Copied!
1
let data = { foo: 'bar' };
2
​
3
$.ajax({
4
url: 'https://usemechanic.com/webhook/0000-0000',
5
method: 'POST',
6
headers: {
7
'content-type': 'application/json'
8
},
9
data: JSON.stringify(data)
10
});
Copied!

Responses

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.

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 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.
Last modified 2mo ago