Skip to main content

Manage Webhooks

Endpoint Descriptions

Register a New Webhook​

POST /vendors/v1/webhooks​

This endpoint registers a new webhook for a vendor to receive specific event notifications. It requires authentication and provides a way for vendors to specify the type of events they want to be notified about, along with the callback URL where the event data will be sent.

Request Body Description​

The request body for registering a webhook must be a JSON object containing the following fields. Each field plays a crucial role in ensuring the webhook functions as intended:

  • event_type determines which events will trigger notifications, allowing vendors to specify their interests.
  • callback_url is essential for defining where the notifications will be sent.
  • secret ensures secure communication by enabling verification of the authenticity of received payloads.

Fields​

  • event_type: string

    • The type of event that will trigger the webhook. Supported values include triggers for machine and deployment events:
      • EVENT_TYPE_MACHINE_CREATED: Triggered when a new machine is created.
      • EVENT_TYPE_MACHINE_UPDATED: Triggered when there is an update to a machine's status.
      • EVENT_TYPE_MACHINE_REMOVED: Triggered when a machine is removed.
      • EVENT_TYPE_DEPLOYMENT_CREATED: Triggered when a new deployment is created.
      • EVENT_TYPE_DEPLOYMENT_UPDATED: Triggered when there is an update to a deployment.
      • EVENT_TYPE_DEPLOYMENT_STOPPED: Triggered when a deployment is stopped.
    • Must be a non-empty string.

  • callback_url: string

    • The URL where the event data will be sent.
    • Must be a valid URL and non-empty string.

  • secret: string (optional)

    • A shared secret used to generate HMAC signatures for securing the payload.
    • Must be a non-empty string if provided.
Example Request Body​
{
  "event_type": "EVENT_TYPE_MACHINE_UPDATED",
  "callback_url": "https://vendor-callback-url.com/webhook",
  "secret": "my-shared-secret"
}

Success Response​

Status Code: 201 Created

Response Body Description​

The response body contains the unique identifier for the registered webhook.

Fields​

  • webhook_id: string
    • The unique identifier for the webhook.

Example Response Body​

{
  "webhook_id": "abcdef12-3456-7890-abcd-ef1234567890"
}

HTTP Status Codes​

The "Register Webhook" endpoint may return the following HTTP status codes based on the outcome of the request:

Success Codes:

  • 201 Created: The request was successful, and the response body contains the webhook ID.

Client Error Codes:

  • 400 Bad Request: The server could not understand the request due to invalid syntax. This status is typically returned if required fields are missing or incorrectly formatted.
  • 401 Unauthorized: The request lacks valid authentication credentials for the target resource.
  • 409 Conflict: The webhook registration conflicts with an existing entry (e.g., same event_type).

Server Error Codes:

  • 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.
Example cURL Request​
curl -X POST "https://api.example.com/vendors/v1/webhooks" \
     -H "Content-Type: application/json" \
     -H 'X-API-Key: <your_api_key>' \
     -d '{
           "event_type": "EVENT_TYPE_MACHINE_UPDATED",
           "callback_url": "https://vendor-callback-url.com/webhook",
           "secret": "my-shared-secret"
         }'

This cURL command registers a new webhook for the MachineUpdated event, specifying callback_url, and a shared secret for securing the communication.

List All Webhooks​

GET /vendors/v1/webhooks​

This endpoint retrieves a list of all registered webhooks for the vendor. It requires authentication to ensure that only authorized users can access their webhook information.

Success Response​

Status Code: 200 OK

Response Body Description​

The response body contains an array of registered webhooks.

Fields​

  • webhooks: array
    • An array of webhook objects, each containing the following fields:
      • webhook_id: string
        • The unique identifier for the webhook.
      • event_type: string
        • The type of event that triggers the webhook.
      • callback_url: string
        • The URL where the event data is sent.
      • secret: string (optional)
        • The shared secret for securing the payload.

Example Response Body​

{
  "webhooks": [
    {
      "webhook_id": "abcdef12-3456-7890-abcd-ef1234567890",
      "event_type": "EVENT_TYPE_MACHINE_UPDATED",
      "callback_url": "https://vendor-callback-url.com/webhook",
      "secret": "my-shared-secret"
    },
    {
      "webhook_id": "1234abcd-5678-ef90-1234-567890abcdef",
      "event_type": "EVENT_TYPE_DEPLOYMENT_UPDATED",
      "callback_url": "https://another-callback-url.com/webhook"
    }
  ]
}

HTTP Status Codes​

Success Codes:

  • 200 OK: The request was successful, and the response body contains the list of webhooks.

Client Error Codes:

  • 401 Unauthorized: The request lacks valid authentication credentials for the target resource.

Server Error Codes:

  • 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.

Delete a Webhook​

DELETE /vendors/v1/webhooks/{webhook_id}​

This endpoint deletes a registered webhook based on the provided webhook_id. It requires authentication to ensure only authorized users can delete their webhooks.

Success Response​

Status Code: 204 No Content

The response does not contain any content, indicating that the webhook was successfully deleted.

HTTP Status Codes​

Success Codes:

  • 204 No Content: The webhook was successfully deleted.

Client Error Codes:

  • 400 Bad Request: The server could not understand the request due to invalid syntax.
  • 401 Unauthorized: The request lacks valid authentication credentials for the target resource.
  • 404 Not Found: The specified webhook_id does not exist.

Server Error Codes:

  • 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.

Example cURL Request​

curl -X DELETE "https://api.example.com/vendors/v1/webhooks/abcdef12-3456-7890-abcd-ef1234567890" \
     -H 'X-API-Key: <your_api_key>'

This cURL command deletes the webhook with the specified webhook_id.

Update a Webhook​

PATCH /vendors/v1/webhooks/{webhook_id}​

This endpoint updates an existing webhook based on the provided webhook_id. It requires authentication to ensure only authorized users can update their webhooks.

Request Body Description​

The request body must be a JSON object containing the fields to be updated. Any combination of the following fields can be included:

Fields​

  • event_type: string (optional)

    • The type of event that will trigger the webhook. Supported values include triggers for machine and deployment events:
      • EVENT_TYPE_MACHINE_CREATED: Triggered when a new machine is created.
      • EVENT_TYPE_MACHINE_UPDATED: Triggered when there is an update to a machine's status.
      • EVENT_TYPE_MACHINE_REMOVED: Triggered when a machine is removed.
      • EVENT_TYPE_DEPLOYMENT_CREATED: Triggered when a new deployment is created.
      • EVENT_TYPE_DEPLOYMENT_UPDATED: Triggered when there is an update to a deployment.
      • EVENT_TYPE_DEPLOYMENT_STOPPED: Triggered when a deployment is stopped.
    • Must be a non-empty string.

  • callback_url: string (optional)

    • The URL where the event data will be sent.
    • Must be a valid URL and non-empty string.

  • secret: string (optional)

    • A shared secret used to generate HMAC signatures for securing the payload.
    • Must be a non-empty string if provided.

Example Request Body​

{
  "callback_url": "https://updated-callback-url.com/webhook"
}

Success Response​

Status Code: 200 OK

Response Body Description​

The response body contains the updated webhook information.

Fields​

  • webhook_id: string
    • The unique identifier for the webhook.
  • event_type: string
    • The type of event that triggers the webhook.
  • callback_url: string
    • The updated URL where the event data is sent.
  • secret: string (optional)
    • The shared secret for securing the payload.

Example Response Body​

{
  "webhook_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "event_type": "EVENT_TYPE_MACHINE_UPDATED",
  "callback_url": "https://updated-callback-url.com/webhook",
  "secret": "my-updated-secret"
}

HTTP Status Codes​

Success Codes:

  • 200 OK: The request was successful, and the response body contains the updated webhook information.

Client Error Codes:

  • 400 Bad Request: The server could not understand the request due to invalid syntax or invalid field values.
  • 401 Unauthorized: The request lacks valid authentication credentials for the target resource.
  • 404 Not Found: The specified webhook_id does not exist.

Server Error Codes:

  • 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.

Example cURL Request​

curl -X PATCH "https://api.example.com/vendors/v1/webhooks/abcdef12-3456-7890-abcd-ef1234567890" \
     -H "Content-Type: application/json" \
     -H 'X-API-Key: <your_api_key>' \
     -d '{
           "callback_url": "https://updated-callback-url.com/webhook"
         }'

This cURL command updates the callback_url for the specified webhook.