Create Webhook Subscription

Description

Create a webhook subscription within your Bold Penguin tenant.

The endpoint returns a webhook subscription object.

NOTE: You cannot use the Enterprise Terminal to edit subscriptions created using this API. Since the webhook interface in the Terminal only supports a subset of the API, you must choose either the Terminal or this API for managing webhook subscriptions.

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
  • Shared secret for validating X-Signature headers
  • Type: String
  • Required: No
• 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
      • Shared secret for validating X-Signature headers
      • Type: String
      • Required: No

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

{
  "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 (verify bearer token from authentication)
• 422: Parameter validation failure (verify the request body)
• 500: Internal server error

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": "",
  "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"
}