Registering a webhook with Pipe17 using pipe17 API.
Pre-requisites:
- An API key with permissions to create a webhook.
- An second API key with permissions to read (and optionally update) the entities that will be reported to the webhook.
Examples:
The example below uses curl, however, you can use any tool or programming language
curl -s -X POST --data '{
{
"url": "https://mywebhook.mydomain.com",
"apikey": "{{ REPLACE WITH YOUR API KEY}}",
"topics": [ "orders", "fulfillments", "products", "inventory" ]
}
}'
-H "Content-Type: application/json"
-H "X-Pipe17-Key: {{ REPLACE WITH PIPE17 KEY }}"
https://api-v3.develop.pipe17.com/api/v3/webhooks
In this example, the API invoker requests callbacks to mywebhook.mydomain.com about orders, fulfillments, products, and inventory items.
The value in the header X-Pipe17-Key is the API key that has permissions to create a webhook.
A successful registration response will look like this
{
"success": true,
"code": 200,
"webhook": {
"webhookId": "e7bdd0a88cd321dd", // Indetifier used for subsequent operations on this webhook (e.g., to delete it)
"url": "https://mywebhook.mydomain.com",
"apikey": "51d355e22411cae6a9ee4b67b0568c93",
"topics": [ "orders", "fulfillments", "products", "inventory" ]
"createdAt": "2021-08-24T14:15:22Z",
"updatedAt": "2021-08-24T14:15:22Z",
"orgKey": "a5ad27e3a383b711" // The id of the organization (account or sub-account) to which this webhook applies
}
}
When an entity of a type listed in topics, for example, an order, that belongs to the organization is created, updated, or deleted, the webhook will be invoked.
Pipe17 will invoke the webhook with the equivalent of this curl example:
curl -s -X POST --data '{
"orgKey": "a5ad27e3a383b711", // The organization to which the affected entity belongs to
"entity": "orders", // One of the entites specified in the webhook registration topics
"action": "create", // Possible actions are create, update and delete
"itemId": "930cfcd3018dffd5", // The Pipe17 Id of that entity (in this example of the order)
"timestamp": "2021-08-24T14:18:31Z", // When the change happened
"requestId": "b020289f41cc0aee" // Unique Id of this invocation (to allow deduplication in case of retries)
}'
-H "Content-Type: application/json"
-H "x-api-key: {{ YOUR API KEY }}"
https://mywebhook.mydomain.com
In the above example notice x-api-key is the value passed to the Pipe17 webhook registration api.
The webhook may then call Pipe17 to retrieve the details of the reported entity. Following the above example, the webhook will retrieve the details of order 930cfcd3018dffd7.
curl -s -X GET -H "Content-Type: application/json"
-H "X-Pipe17-Key: {{ YOUR PIPE17 API KEY }}"
https://api-v3.pipe17.com/api/v3/orders/930cfcd3018dffd5
n the above example, the above-mentioned second API key is used to retrieve order details. For security reasons it is recomened to create two separate keys, although one can create a single key for both webhook registration and data processing.