Getting started with Pipe17 Webhooks

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 930cfcd3018dffd5.

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

In the above example, the second API key referenced by "{{ YOUR PIPE17 API KEY }}" is used to retrieve order details. For security reasons it is recommend to create two separate keys, although one can create a single key for both webhook registration and data processing.

Note:

• If Pipe17 cannot reach the endpoint, it will retry sending 3 times over 5 minutes. After that the event is removed from the queue.
• If we do reach the endpoint, but the endpoint returns any HTTP status, the event will be considered delivered and will be done from the queue.