Guides

Webhook Configuration

Suggest Edits

A WebhookConfiguration represents location and credentials that Pax8 will use for webhook notifications. The url is the address Pax8 sends webhook payload to. The sharedSecret represents credentials that Pax8 will send as a header in the webhook request to authorize to your system. You can assign a name to the authorization header that Pax8 will send, and Pax8 will generate and return a shared credential that will be used when sending a webhook.

  • You cannot change the ProvisionerWebhook information for a previous Provision Attempt
  • credential values are only returned during create. In all other responses, they are returned as *****

Endpoints

Get All Webhook Configurations for a Provisioner

Get One Webhook for a Provisioner

Get Latest Webhook for a Provisioner

Create a Webhook Configuration for a Provisioner

  • Create a Webhook Configuration for a Provisioner
    • Webhook Configurations are immutable. Only the latest configuration's data will be used for new Provision Notifications. In order to change where Pax8 sends your webhook, or the credentials we should send, create a new Webhook Configuration.
    • Values for the header field must comply with HTTP header specifications
      • If you do not specify a value, the default is pax8ApiTokenV1
    • URL's should not contain any query parameters (for example ?vendorParam={value})
    • Pax8 generates the value for credential when a new webhook configuration is created. The credential is only available in the Create response, so make sure to record the value.
  • POST /provisioners/{provisionerId}/webhooks

The Webhook Object

{
    "id": "ff50b383-0ba6-4fc4-ad30-f19483c1acfb",
    "url": "https://example.com",
    "sharedSecret": {
        "header": "pax8ApiTokenV1",
        "credential": "credential"
    },    
    "createdDate": "2022-10-03T10:15:30Z"
}

Webhook Configuration Guide

You want to setup a new webhook so you first you make the following request to get your provisionerId:

curl --request GET \
     --url https://api.pax8.com/v2/provisioners \
     --header 'accept: */*' \
     --header 'authorization: Bearer TOKEN'

This will return a response similar to

{
  "content": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "createdDate": "2025-08-05T17:01:58.621Z",
      "vendorId": "e20b8d09-a53d-4355-97dc-06ce46218a89",
      "name": "string"
    }
  ],
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  }
}

Now you are able to make a new Webhook Configuration via the following request:

curl --request POST \
     --url https://api.pax8.com/v2/provisioners/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks \
     --header 'accept: */*' \
     --header 'authorization: Bearer TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
  "sharedSecret": {
    "header": "testAuthorization"
  },
  "url": "https://test-server.com"
}
'

Upon making that request you receive a response such as this one. You would note down this credential as you as that is the only time you will be able to view it:

{
    "id": "ff50b383-0ba6-4fc4-ad30-f19483c1acfb",
    "url": "https://test-server.com",
    "sharedSecret": {
        "header": "testAuthorization",
        "credential": "abc123"
    },    
    "createdDate": "2025-08-04T16:28:02.850Z"
}

This means that whenever Pax8 sends a webhook notification to you, our request would look something like this:

curl --request POST 
 --url https://test-server.com \
 --header 'testAuthorization: abc123' \
 --data '{<provisionNotificationBody>}'

Updated about 1 month ago