Ankorstore Webhooks API

ℹ️ This section describes the API endpoints which can be used for managing webhook subscriptions.## 💡 OverviewIn order to be able to manage Webhook Subscriptions via API you should understand the relationship modelaround webhook notifications system. In general, a Webhook Subscription always contains a list of chosen eventsand always belongs to an application. More on this later.### ApplicationApplication is a representation of a single private integration. Whenever you create a new set of credentials foraccessing API in your account, under the hood you create an Application entity. Once created, the entity allows youto attach as many Webhook Subscriptions as needed. It means, there's no way to manage Webhook Subscriptions outside ofApplication context and this restriction is also reflected in the current API architecture.### Webhook SubscriptionWebhook Subscription is an entity representing "an intent of receiving HTTP requests to the specified URL wheneverone of the chosen Webhook Subscription Events is triggered on the platform". For every new URL you should create aseparate Webhook Subscription.### Webhook Subscription EventsWebhook Subscription Event is a name of the corresponding event fired on certain conditions on the platform. There area list of only valid and supported events which can be used in the Webhook Subscription management. You can fetch thislist using a corresponding [endpoint](#tag/Webhooks/operation/get-available-webhook-events)## 💡 How to create a new webhook subscription?### 1. Find ApplicationIDAs it was mentioned above, Webhook Subscription always belong to some application. Hence, you should start fromfinding out the ID of the target Application in order to link the new Webhook Subscription to it. For this purposeyou should use [List Applications](#tag/Applications/operation/list-applications) endpoint. This endpoint returnsa list of all available Applications in your account, so you could identify the needed one by `name`, `developerEmail`or `clientId` in the Application resource body:`GET https://ankorstore.com/api/v1/applications````json{ "data": { "id": "43efbfbd-bfbd-1eef-1e6a-6200efbfbdef", "type": "application", "attributes": { "name": "My Application", "developerEmail": "dev@acme.com", "clientId": "k322k7frs87e8w7hri3jkke7ry7", "clientSecret": null } }}```**NOTE**: The client secret in the response is always `null` due to security reasons. The actual client secretcan be seen only via UI and only once - during the creation of the application.### 2. Find valid webhook events to subscribe toNext step should be to find the valid names of the webhook events which you could use in the create webhook requestpayload:`GET https://ankorstore.com/api/v1/webhook-subscriptions/events````json{ "data": [ { "type": "webhook-subscriptions/events", "id": "order.brand_created" }, { "type": "webhook-subscriptions/events", "id": "order.brand_accepted" } ]}```You can find detailed description of each event in the [dedicated section](#tag/Webhook-Subscription) of the docs.### 3. Create webhook subscriptionNow you are all set for creating actual webhook subscription. The prerequisites for this step are:- The Application ID from step 1 (`43efbfbd-bfbd-1eef-1e6a-6200efbfbdef` in this example)- The chosen events from step 2 (e.g. `order.brand_created` and `order.brand_accepted`)With this setup the final request should look like:`POST https://ankorstore.com/api/v1/webhook-subscriptions````json{ "data": { "type": "webhook-subscriptions", "attributes": { "url": "https://my-app.com/webhook-listener", "events": [ "order.brand_created", "order.brand_accepted" ] }, "relationships": { "application": { "data": { "type": "applications", "id": "43efbfbd-bfbd-1eef-1e6a-6200efbfbdef" } } } }}```After this request is succeeded, you will start receiving notification about chosen events on the chosen URL.## 💡 How to manage existing Webhook Subscriptions?For most of the operations with an existing Webhook Subscription you need to fetch its ID first. It can be achieved byusing [List Applications](#tag/Applications/operation/list-applications) endpoint and explicit includingthe Webhook Subscription resource into the response.`GET /api/v1/applications?include=webhookSubscriptions````json{ "data": { "id": "`43efbfbd-bfbd-1eef-1e6a-6200efbfbdef", "type": "applications", "attributes": {}, "relationships": { "webhookSubscriptions": { "data": [ { "type": "webhook-subscriptions", "id": "a863e15d-3d20-4af2-b92b-d9590a4a9606" } ] } } }, "includes": [ { "type": "webhook-subscriptions", "id": "a863e15d-3d20-4af2-b92b-d9590a4a9606", "attributes": { "url": "https://my-app.com/webhook-listener", "events": [ "order.brand_created", "order.brand_accepted" ], "signingSecret": "LQxZs6kiSyNr45hjT32OsntYddzH4BvToLIQcgSL" } } ]}```The data in this response gives you an idea about the current Webhook Subscription state and also lets you updateor delete Webhook Subscriptions, whenever needed. For updating or deleting Webhook Subscription you need to use theWebhook Subscription ID received in the response (`a863e15d-3d20-4af2-b92b-d9590a4a9606` in this particular case). Pleaserefer to the [Update webhook subscription](#tag/Webhooks/operation/update-application-webhook-subscription)and [Delete webhook subscription](#tag/Webhooks/operation/delete-application-webhook-subscription) endpointsfor detailed information.