Provision Notification

Pax8 uses Provision Notification webhooks to notify Provisioners of new Provisioning activity. A Provision Notification webhook should contain all the data you need to complete an provisioning request from Pax8.

Configuring Your Webhook

Find out how to customize where we send Provision Notifications and how we authenticate to your API on the Webhook Configuration page.

Provision Notification Structure

A Provision Notification contains a Provision Request, a Provision Detail, and a Provision Attempt.
Shared Secrets from a Webhook Configuration are sent in HTTP headers. More here
For more information on isSimulation, see the testing section of our docs here

{
    "isSimulation": false,
    "provisionRequest": {
        "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
        "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
        "partnerName": "Example Partner Name",
        "partnerDomain": "partner.com",
        "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02",
        "partnerAddress": {
            "street": "123 Partner Ave.",
            "street2": "Unit b",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99",
        "companyName": "Example Company Name",
        "companyDomain": "company.com",
        "companyAddress": {
            "street": "123 Company Ave.",
            "street2": "Unit c",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1",
        "productName": "Product ABC",
        "quantity": 1,
        "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064",
        "type": "NetNew",
        "createdDate": "2024-04-08T19:54:03Z",
        "commitmentTermMonths": 12,
        "commitmentTermEndDate": "2025-04-08T19:54:03Z",
        "commitment": {
            "term": {
                "months": 12,
                "endDate": "2025-04-08T19:54:03Z"
            },
            "volume": {
                "minAmount": 1,
                "maxAmount": 10,
                "unitOfMeasure": "Users",
                "months": 1
            }
        },
        "billingTerm": "Monthly"
    },
    "provisionDetail": {
        "id": "5c425efa-60be-4bac-98b4-d3dff9099143",
        "provisionRequestId": "50f31e66-9a01-43a8-b0f8-14c288bac5da",
        "details": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]",
            "changeOfChannel": "Yes"
        },
        "createdDate": "2022-10-03T10:15:30Z"
    },
    "provisionAttempt": {
        "id": "3a11dbb9-226d-4788-86cd-4c6601da81e9",
        "provisionDetailId": "8fcf68db-c30e-4f34-b773-bc1631cd1fef",
        "webhookId": "21110b5d-55b1-4cdf-82f7-2bcc9fef6c41",
        "status": "Acknowledged",
        "createdDate": "2022-10-03T10:15:30Z"
    }
}

Null Values

It's important to note that if any of the values above would be null, the API will omit them from the notification body completely. This rule applies to all requests and responses coming out of the Pax8 API.

Where We Send Provision Notifications

Pax8 sends each Provision Notification to the URL on the most recent Webhook Configuration configured by a Provisioner.
Each Provision Notification, by way of the provisionAttempt, contains a reference to the associated webhook configuration in the webhookId field.
For more information about how to configure webhooks see the Webhook Configuration page.

Acceptable Status codes

Pax8 only accepts the following HTTP status codes to acknowledge a Provision Notification:
- 200
- 201
- 202

If your url redirects with a 301, you need to adjust your configuration to one that doesn't redirect.
Redirects will cause webhook delivery to fail.

📘
Validation and processing of the Provision Notification should not be done before the webhook is acknowledged with one of the acceptable status codes.

All processing and validation should be happening in an asynchronous manner after the lightweight acknowledgement is sent, and the vendor system confirms that they have captured the request into their system. If anything fails during your asynchronous validation process you should respond with a ProvisionResult with the status Fail and an error message.

For example, if the ProvisionRequest is missing a required detail for provisioning, the webhook should still be acknowledged with a 200, 201 or 202 code. And then in the subsequent ProvisionResultthat is sent to Pax8 the the "missing required detail" error would be sent as a failed result.

Retries

Status codes not listed above will cause Pax8 to fail the current ProvisionAttempt and retry the webhook.
- Pax8 will attempt to retry a Webhook delivery 3 times.
- We record each webhook delivery as a ProvisionAttempt
Pax8 does not accept a ProvisionResult for a failed ProvisionAttempt.
The Pax8 system waits approximately 15 seconds before retrying

Configuring Your Webhook