Skip to main content

Create Webhook Subscription

Description

Create a webhook subscription within your Bold Penguin tenant.

The endpoint returns a webhook subscription object.

Endpoint

Staging

https://hookshot-uat.beta.boldpenguin.com/hooks

Production

https://hookshot.boldpenguin.com/hooks

Authentication

This endpoint requires an access_token from the authentication endpoint in the same environment with the appropriate permissions. Include it as a bearer token in an Authorization header for the request.

Authorization: Bearer <access_token>

Methods

POST

Request Syntax

POST /hooks

Request Payload

{
"active": boolean,
"events": [
"<string>",
"<string>",
...
],
"header": "<string>",
"secret": "<string>",
"url": "<string>"
}

Request Parameters

The only requirement is a non-blank url parameter. However, for a subscription to receive events it must have the following minimum configuration:

  1. A valid, accessible URL endpoint
  2. One or more valid event types (or a wildcard)
  3. active set to true

JSON Parameters

  • active
    • Enable the delivery of webhook payloads by setting this to true
    • You must have at least one event subscription to set to true
    • Type: Boolean
    • Required: No (default is false)
  • events
    • An array of valid subject or subject:action strings (see Event Subjects & Payloads for allowed values)
    • Or the wildcard string ("*")
    • Type: Array of strings
    • Required: No
  • header
    • Static HTTP header for authentication or other purposes.
    • Type: String (format Name: Value)
    • Required: No
  • secret
  • url
    • A valid URL string to receive events
    • Type: URL string
    • Required: Yes

Response Syntax

{
"id": "<UUID>",
"active": <boolean>,
"confirmed": false,
"events": [
"<string>",
"<string>",
...
],
"config": {
"url": "<string>",
"secret": "<string>",
"header": "<string>"
},
"owner_id": "<UUID>",
"tenant_id": "<UUID>",
"created_at": "<Timestamp>",
"updated_at": "<Timestamp>"
}

Response Elements

  • id
    • A globally unique ID for this subscription within your tenant.
    • Type: UUID
  • active
    • Is this subscription currently receiving events
    • Type: Boolean
  • confirmed
    • Unused (always false)
    • Type: Boolean
  • events
    • An array of valid subject or subject:action strings (see Event Subjects & Payloads for allowed values)
    • Or a wildcard ("*")
    • Type: Array of strings
  • config
    • Configuration object containing url, secret, and header
    • Type: Configuration object
    • Object elements:
      • url
        • A valid URL string to receive events
        • Type: URL string
        • Required: Yes
      • header
        • Static HTTP header for authentication or other purposes.
        • Type: String (format Name: Value)
        • Required: No
      • secret

Validation Errors

The API performs specific validation on url and header values submitted as part of create and update operations. Validation failures result in a 422 error with one of the following response payloads.

{
"header": [
"colon separated key value pair"
]
}

URL

{
"url": [
"can't be blank"
]
}

Status Codes

  • 201: Created
  • 400: Bad request (verify JSON body is well formed)
  • 401 Unauthorized: The necessary authentication credentials are not present in the request or are incorrect.
  • 422: Parameter validation failure (verify the request body)

Examples

Example Request

curl --request POST \
--url https://hookshot.boldpenguin.com/hooks \
--header 'authorization: Bearer <access-token>' \
--header 'content-type: application/json' \
--data '{
"url": "https://chuck-webhook.ngrok.io",
"header": "User: Chuck",
"secret": "503bec91ecdf413562f69336b597e5b78550f548",
"active": true,
"events": [
"*"
]
}'

Example Responses

{
"id": "e6db9c1a-d15f-4248-81fa-5b61fc321def",
"active": true,
"confirmed": false,
"events": [
"*"
],
"config": {
"url": "https://chuck-webhook.ngrok.io",
"secret": "",
"header": "User: Chuck"
},
"owner_id": "46912066-9be9-4a04-97ea-5505a1acde",
"tenant_id": "94f43d40-a61c-4d4d-918e-d888aabe906a",
"created_at": "2020-09-24T13:47:16.856Z",
"updated_at": "2020-09-24T13:47:16.856Z"
}