Provision Notification Webhook

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 webhooks and how we authenticate to your API on the Webhook Configuration page

Webhook Structure

• A Provision Notification Webhook contains a ProvisionRequest, ProvisionDetail, and ProvisionAttempt.
• Shared Secrets from a Webhook Configuration are sent in HTTP headers. The Header name is customizable.
• For more information on isSimulation, see the testing section of our docs

{
    "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",
      	"billingTerm": "Monthly
    },
    "provisionDetail": {
        "id": "5c425efa-60be-4bac-98b4-d3dff9099143",
        "provisionRequestId": "50f31e66-9a01-43a8-b0f8-14c288bac5da",
        "details": {
            "key": "value"
        },
        "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.

When We Send Provision Notification Webhooks

• Pax8 sends a webhook for every new ProvisionRequest
  • Each webhook contains the ProvisionDetail entered by the user at checkout
• Pax8 will include a ProvisionAttempt in the webhook, which can be used to return a ProvisionResult

Where we Send Provision Notification Webhooks

• Pax8 sends each webhook to the latest webhook configured for a Provisioner
• Each webhook contains a reference to the associated webhook configuration in the webhookId field
• For more information about how to configure webhooks see the Provisioner Webhooks page

Acceptable Status codes

• Pax8 accepts the following HTTP status codes to acknowledge webhooks
  • 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.

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.
• Webhook waits approximately 15 seconds before retrying.

Successful Example

1. Pax8 Sends Webhook and creates a ProvisionAttempt
2. Provisioner API returns HttpStatus 200
   • Pax8 expects the provisioner api to simply acknowledge the Provision Notification Webhook, and reply with a 200, 201, or 202. The provisioner api should not do any synchronous processing or validation at this time.
3. Pax8 marks the ProvisionAttempt as acknowledged
4. Provisioner processes the request asynchronously. At this time that would include validating request data, and then provisioning services.
5. Provisioner posts a ProvisionResult for the ProvisionAttempt
   • If there were any errors during validation or provisioning, send a ProvisionResult with a Fail status, and include details in the errorMessage
   • If provisioning was successful, send a ProvisionResult with a Success status

Transient Error Example

1. Pax8 Sends Webhook and creates ProvisionAttempt_1
2. Provisioner API returns HttpStatus 500
3. Pax8 marks ProvisionAttempt_1 as failed
4. Pax8 Sends Webhook and creates a ProvisionAttempt_2
5. Provisioner API returns HTTPStatus 200
6. Pax8 marks the ProvisionAttempt_2 as successful
7. Provisioner returns a ProvisionResult for ProvisionAttempt_2