Webhook Configuration

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 ProvisionAttempt.
credential values are only returned during create. In all other responses, they are returned as *****

GET  /provisioners/{provisionerId}/webhooks
GET  /provisioners/{provisionerId}/webhooks/{webhookId}
GET  /provisioners/{provisionerId}/webhooks/latest

POST /provisioners/{provisionerId}/webhooks

Webhook Configuration Object

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

Create a Webhook Configuration

Provisioner Webhooks are immutable. Only the latest Provisioner Webhook data will be used for new notifications. To update where Pax8 sends your webhook or the credentials we should send, create a new Provisioner Webhook and future webhooks will use the new data.
Values for the header field must comply with HTTP header specifications
- If you do not specify a value, the default is pax8ApiTokenV1
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
{
    "url": "https://example.com",
    "sharedSecret": {
        "header": "pax8ApiTokenV1"
    }
}

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

After the webhook configuration is created

Get all Webhook Configurations for a Provisioner

GET /provisioners/{provisionerId}/webhooks

{
    "page": {
        "size": 10,
        "totalElements": 10,
        "totalPages": 10,
        "number": 1
    },
    "content": [
        {
            "id": "ff50b383-0ba6-4fc4-ad30-f19483c1acfb",
            "url": "https://example.com",
            "sharedSecret": {
                "header": "pax8ApiTokenV1",
                "credential": "*****"
            },
            "createdDate": "2022-10-03T10:15:30Z"
        }
    ]
}

Get one Webhook for a Provisioner

GET /provisioners/{provisionerId}/webhooks/{webhookId}

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

Get Latest Webhook for a Provisioner

GET /provisioners/{provisionerId}/webhooks/latest

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

Webhook Configuration Example

Let's say you make a POST request to create a new webhook configuration that looks like the one below:

POST /provisioners/{provisionerId}/webhooks
{
    "url": "https://test-server.com",
    "sharedSecret": {
        "header": "testAuthorization"
    }
}

And then you received a response that looked like this:

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

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>}'