Subscriptions API endpoints

Creating a subscription

Use the Create push notification subscription endpoint to create a subscription.

This endpoint processes your request synchronously and returns 204 No Content upon success. The subscription is active immediately.

An example of a webhook subscription request is provided below:

Create webhook subscription example

{
  "resources": ["PROCESS_STATUS"],
  "eventDestination": "https://www.bol.com/webhook",
  "subscriptionType": "WEBHOOK"
}

To create a GCP Pub/Sub subscription:

Create GCP Pub/Sub subscription example

{
    "resources": ["PROCESS_STATUS", "COMPETING_OFFER"],
    "eventDestination": "projects/my-project-id/topics/bol-pubsub-topic", (1)
    "subscriptionType": "GCP_PUBSUB"
}

1	This is the full path to your Pub/Sub topic.

To create an AWS SQS subscription:

The SQS Queue must reside in one of the EU regions.

Create AWS SQS subscription example

{
    "resources": ["PROCESS_STATUS", "COMPETING_OFFER"],
    "eventDestination": "https://sqs.eu-central-1.amazonaws.com/12341234/bol-sqs-queue", (1)
    "subscriptionType": "AWS_SQS",
    "identity": "arn:aws:iam::12341234:role/bol-sqs-role" (2)
}

1	This is the URL to your SQS queue. It must reside in one of the European regions.
2	This is the `ARN` for the role you created for Bol to assume.

The response contains the id of the newly created subscription, which you use for all subsequent operations.

For more information on the request and response body, see the Redoc.

Retrieving all subscriptions

Use the Get push notification subscriptions endpoint to retrieve a list of all the configured push notification subscriptions for your account.

For more information on the request and response body, see the Redoc.

Retrieving a subscription by ID

Use the Get push notification subscription by id endpoint to fetch a subscription by its subscriptionId and verify its details.

An example of the response is provided below:

Get subscription response example

{
  "id": "1234",
  "resources": ["PROCESS_STATUS"],
  "eventDestination": "https://www.bol.com/webhook",
  "subscriptionType": "WEBHOOK",
  "enabled": true
}

For more information on the request and response body, see the Redoc.

Testing a subscription

Use the Send test push notification for subscriptions endpoint to verify connectivity for an existing subscription using its subscriptionId.

When the subscription exists and is reachable, a test message is dispatched to the corresponding eventDestination. The endpoint returns a confirmation response so you can verify what was sent.

Test notification response example

{
  "resourceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "resource": "PROCESS_STATUS",
  "type": "TEST"
}

For more information on the request and response body, see the Redoc.

Updating a subscription

Use the Update push notification subscription endpoint to modify an existing subscription by its subscriptionId.

For example, you can use this to change the eventDestination of your endpoint or the event types that you want to subscribe to.

This endpoint processes your request synchronously and returns 204 No Content upon success.

An example of the request body is provided below:

Update subscription request example

{
    "resources": ["PROCESS_STATUS"],
    "eventDestination": "https://www.bol.com/webhook",
    "subscriptionType": "WEBHOOK",
    "enabled": true (1)
}

1	Note that this field is optional and will be set to `true` if not provided.

For more information on the request and response body, see the Redoc.

NOTE

To remove a specific resource from the subscription, submit the list of resources you want to subscribe to, excluding the one you wish to remove.
To add a new resource, submit the entire list of resources you wish to subscribe to, including the new one you intend to add.

Deleting a subscription

Use the Delete push notification subscription endpoint to delete an existing subscription entirely by subscriptionId.

This endpoint processes your request synchronously and returns 204 No Content upon success.

For more information on the request and response body, see the Redoc.

Retrieving public keys for signature validation

Use the Retrieve public keys for push notification signature validation endpoint to retrieve a list of public keys that should be used to validate the signature header for push notifications.

Upon making the request, you will receive a list of public keys. It is advisable to cache these keys since they do not frequently change. However, if you encounter a message signed with a new keyID that is not present in your cached list, you can request the keys again to obtain the public key that belongs to that specific keyset.

An example of the response from the API is provided below:

Signature keys example

GET /subscriptions/push-notifications/signature-keys
{
    "signatureKeys": [{
        "id": "0",
        "type": "RSA",
        "publicKey":"PUBLICKEY"
    }]
}

The contents of this response are:

id - Specifies the ID of the keyset with the reference keyId in the signature header.
type - Specifies the type of key. In this case, it is an RSA public key.
publicKey - Specifies the Base64 encoded X.509 public key. To load it, first decode it from Base64 and then load it as an X.509-spec public key.

For more information on the request and response body, see the Redoc.