Ankorstore Webhooks API

ℹ️ This section describes the API endpoints which can be used for managing webhook subscriptions. ## 💡 Overview In order to be able to manage Webhook Subscriptions via API you should understand the relationship model around webhook notifications system. In general, a Webhook Subscription always contains a list of chosen events and always belongs to an application. More on this later. ### Application Application is a representation of a single private integration. Whenever you create a new set of credentials for accessing API in your account, under the hood you create an Application entity. Once created, the entity allows you to attach as many Webhook Subscriptions as needed. It means, there's no way to manage Webhook Subscriptions outside of Application context and this restriction is also reflected in the current API architecture. ### Webhook Subscription Webhook Subscription is an entity representing "an intent of receiving HTTP requests to the specified URL whenever one of the chosen Webhook Subscription Events is triggered on the platform". For every new URL you should create a separate Webhook Subscription. ### Webhook Subscription Events Webhook Subscription Event is a name of the corresponding event fired on certain conditions on the platform. There are a list of only valid and supported events which can be used in the Webhook Subscription management. You can fetch this list using a corresponding [endpoint](#tag/Webhooks/operation/get-available-webhook-events) ## 💡 How to create a new webhook subscription? ### 1. Find ApplicationID As it was mentioned above, Webhook Subscription always belong to some application. Hence, you should start from finding out the ID of the target Application in order to link the new Webhook Subscription to it. For this purpose you should use [List Applications](#tag/Applications/operation/list-applications) endpoint. This endpoint returns a 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 secret can be seen only via UI and only once - during the creation of the application. ### 2. Find valid webhook events to subscribe to Next step should be to find the valid names of the webhook events which you could use in the create webhook request payload: `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 subscription Now 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 by using [List Applications](#tag/Applications/operation/list-applications) endpoint and explicit including the 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 update or delete Webhook Subscriptions, whenever needed. For updating or deleting Webhook Subscription you need to use the Webhook Subscription ID received in the response (`a863e15d-3d20-4af2-b92b-d9590a4a9606` in this particular case). Please refer to the [Update webhook subscription](#tag/Webhooks/operation/update-application-webhook-subscription) and [Delete webhook subscription](#tag/Webhooks/operation/delete-application-webhook-subscription) endpoints for detailed information.