Register webhook

POST /notifications/v1/webhooks

The registerWebhook operation enables you to register the target URL for a webhook, which can then be used to receive notifications from the API Platform. This requires you to implement a callback HTTPS server on the client side, which is capable of processing the notification messages from the API Platform server.

For example, this can be useful if you have purchased products from the Catalog and are waiting for completion of delivery. If you have registered a webhook, you will receive a notification from the API Platform as soon as delivery is complete, instead of having to poll the getPurchase operation repeatedly.

Required parameters

Target URL

The targetURL parameter specifies the URL of the callback HTTPS server you have implemented to receive callback notifications from the API Platform server.

Optional parameters

Authentication

The auth parameter can be used to configure authentication to protect access to your callback HTTPS server.

Currently following types of authentication is supported:

  • basic

  • client_credential

  • noauth

Basic

The auth parameter is formatted as a JSON object with the following properties:

  • type — Authentication type. Use basic to support this authentication method

  • username — Username credential for your callback HTTPS server.

  • password — Password credential for your callback HTTPS server.

Client Credentials

The auth parameter is formatted as a JSON object with the following properties:

  • type — Authentication type. Use client_credential to support this authentication method

  • clientID — ClientID for your callback HTTPS server.

  • clientSecret — ClientSecret for your callback HTTPS server.

  • tokenURL — URL of your authentication server.

No Auth

The auth parameter is formatted as a JSON object with the following properties:

  • type — Authentication type. Use noauth to support this authentication method

Example

Request

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --location "${API_BASE_URL}/api/notifications/v1/webhooks" \
--header "Content-Type: application/json" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data '{
    "targetURL": "https://example.com",
    "auth": {
        "type": "basic",
        "username": "USERNAME",
        "password": "PASSWORD"
    }
}'

Response

On success, returns a 200 status code and a JSON object containing a copy of the webhook registration record, which includes the unique identifier (UUID) for the webhook in the id property. The status of the returned webhook registration record can be either active or deactivated (for example, if the webhook was deactivated by calling deactivate webhook).

{
  "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "createdAt": "2006-01-02T15:04:05Z07:00",
  "updatedAt": "2006-01-02T15:04:05Z07:00",
  "targetURL": "https://example.com/notify",
  "auth": {
    "type": "basic",
    "username": "USERNAME"
  },
  "status": "active"
}