Skip to main content

Getting Started with Webhooks Guide

Overview

It's easy to get set up with webhooks using Bold Penguin's API!

This guide will show you how to:

Depending on your familiarity with webhooks, HTTP, and software tools this guide should take between 30 minutes and 1 hour to complete. After which, you will have the tools and knowledge you need to interact with Bold Penguin's Webhooks API.

Let's get started!

Prerequisties

  • Bold Penguin will provide you with a unique Client ID and Client Secret for your beta envrionment and your production environment.
  • This guide assumes familiarity with command line interfaces.
  • This guide assumes familiarity with basic HTTP operations such as GET, PUT, POST, and DELETE.

Authenticate

Before creating a new webhook subscription, you must generate an access token using the Bold Penguin Authenticate API. This token will be used for subsequent API requests and expires after 12 hours.

If 12 hours have passed you will need to create a new access token using the Authenticate API in order to interact with the Bold Penguin API.

How to Generate Your Access Token

There are 3 steps required to generate a valid access token. This token is used to authenticate your API requests to Bold Penguin and is valid for 12 hours upon creation. You can create any number of additional tokens as needed following these steps.

Step 1: Apply Encoding

Combine the Client ID and Client Secret that you obtained from Bold Penguin and use Base64 encoding to create a basic authentication header to use for your request.

In place of client_id:client_secret in the code samples below, insert your own Client ID and Client Secret values, remembering to separate the values using a colon.

macOS or Linux Using Terminal

echo -n 'clientid:clientsecret' | base64

Windows Using Command Promp

powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"clientid:clientsecret\"))"

Web Converter

There are various tools available on the web that will encode your Client ID and Client Secret. These tools are ok for beta environment terminals, but we recommend using a Terminal command or software such as Postman instead.

After executing this command, you will receive an encoded value that you will use in the next step. Copy this value.

Step 2: Send HTTP Request

After converting your Client ID and Client Secret using Base64 encoding in the previous step, you can execute an HTTP request to generate your access token. This access token will be used for subsequent API requests such as creating a webhook subscription.

To generate your access token you will send an HTTP request to Bold Penguin with your encoded Client ID and Client Secret.

Bold Penguin hosts two endpoints, one for your beta environment and one for your production environment. For executing commands you can replace the URL with either the beta environment endpoint or the production endpoint listed here:

Beta Environment

https://boldpenguin-auth-uat.beta.boldpenguin.com/auth/token?grant_type=client_credentials

Production

https://boldpenguin-auth.boldpenguin.com/auth/token?grant_type=client_credentials

For this guide we will use the beta environment URL in our HTTP request to obtain an access token.

macOS or Linux Using Terminal

curl --request POST --url 'https://boldpenguin-auth-uat.beta.boldpenguin.com/auth/token?grant_type=client_credentials' --header 'authorization: Basic your_token_here'

Windows Using Command Prompt

Windows does not natively support cURL and so the software to execute HTTP requests from your device has to be installed separately. You can install the latest version of cURL for Windows here

curl --request POST --url 'https://boldpenguin-auth-uat.beta.boldpenguin.com/auth/token?grant_type=client_credentials' --header 'authorization: Basic your_token_here'
  • Note to include the entire token here including ==

Other Methods

You can also use tools such as Postman to execute HTTP requests using cURL.

Step 3: Obtain Token

After successfully executing the access token request, Bold Penguin will return a JSON payload containing your access token, time to expire, and other information. For the purposes of this guide, the only piece of information we need to extract is the access token itself.

The JSON package will look similar to the example below which contains mock data:

{
"access_token": "5dg1zLPG9MR7Z1jLaKRzCN5T",
"token_type": "bearer",
"expires_in": 43200,
"refresh_token": "eLDHQHqeCHEdcJrtVc9kgH52",
"scope": "",
"uid": "8845bb81-y3vb-48d6-a75e-49b39ed6e023",
"info": {
"name": "Mike Jones",
"email": "mike.jones@gmail.com",
"first_name": "Mike",
"last_name": "Jones",
...
}

Copy the access_token value from your own request to use in creating your webhook subscription.

Create a Webhook Subscription

Now that you've obtained an access token, it's time to create a webhook subscription using Bold Penguin's Create Webhook Subscription API.

Before creating a new subscription, you need a location for the event payload to go. There are many options such as ngrok and Request Bin. For this guide we will use Request Bin, which will require creating an account.

Set up Request Bin to Receive Events

Step 1: Navigate to Request Bin Website

Navigate to https://requestbin.com in your browser.

Step 2: Select Create Request Bin

Step 3: Create an account with Pastebin.
Step 4: Copy Request Bin URL

Create Webhook Subscription Using cURL Request

After creating an account and setting up a Request Bin URL, you can now add that URL to a cURL command that will be used to create a webhook subscription.

Copy the following examples depending on your platform, and replace the bearer token QBM6779DsxX4rsLTc66UpKMNst with your token, and replace the url https://eoqhsochuurqh5n.m.pipedream.net with the Request Bin URL that you copied in Step 4.

Webhook subscriptions require a few configuration options before you can make use of them. As a general rule, for a subscription to receive events it must have the following minimum configuration, which is what is used for our guide:

  • A valid, accessible endpoint URL
  • One or more valid events types (or * for all events)
  • Active set to true

After replacing the bearer token and URL with your information, execute the command.

macOS or Linux Using Terminal

curl --location --request POST 'https://hookshot-uat.beta.boldpenguin.com/hooks' --header 'Authorization: Bearer QBM6779DsxX4rsLTc66UpKMNst' --header 'Content-Type: application/json' --data-raw '{
"active": true,
"events": ["*"],
"url": "https://eoqhsochuurqh5n.m.pipedream.net"
}'

Windows Using Command Prompt

curl --location --request POST 'https://hookshot-uat.beta.boldpenguin.com/hooks' --header 'Authorization: Bearer QBM6779DsxX4rsLTc66UpKMNst' --header 'Content-Type: application/json' --data-raw '{
"active": true,
"events": ["*"],
"url": "https://eoqhsochuurqh5n.m.pipedream.net"
}'

If you successfully executed the cURL command to create a webhook subscription you should receive a response in your command line similar to the example below. Note the id field and value, and copy the value for the next step.

{
"id": "51633426-e877-rt2d-bccc-jkl843142419",
"active": true,
"confirmed": false,
"events": [
"*"
],
"config": {
"url": "https://eoqhsochuurqh5n.m.pipedream.net"
},
"owner_id": "3e467c3d-eef7-4162-a480-7d21c0897e1e",
"tenant_id": "c1224fd1-cf0b-4729-a80b-33516bd2672c",
"created_at": "2022-05-13T17:55:25.883Z",
"updated_at": "2022-05-13T17:55:25.883Z"
}

List Webhook Subscriptions

Now that you've created a new webhook subscription, you can verify that the webhook subscription has been created by listing the webhook subscriptions on your Tenant using the List Webhooks API.

macOS, Linux Terminal, or Windows Command Prompt

curl --location --request GET 'https://hookshot-uat.beta.boldpenguin.com/hooks' --header 'Authorization: Bearer GTM68DSx4ukrLVc6aUpKMNsl'

Example Response Depending on how many webhook subscriptions you have on your Tenant you may receive multiple lines of responses for each webhook subscription. In this guide, note your id from the previous section should match at least one of the ids from the response from the List Webhooks API.

{
"id": "51633426-e877-rt2d-bccc-jkl843142419",
"active": true,
"confirmed": false,
"events": [
"*"
],
"config": {
"url": "https://eoqhsochuurqh5n.m.pipedream.net"
},
"owner_id": "3e467c3d-eef7-4162-a480-7d21c0897e1e",
"tenant_id": "c1224fd1-cf0b-4729-a80b-33516bd2672c",
"created_at": "2022-05-13T17:55:25.883Z",
"updated_at": "2022-05-13T17:55:25.883Z"
}

Receive a Webhook Event

Now that we've successfully created a webhook subscription and verified that the webhook subscription exists and is active, we can use our beta environment Terminal to create a webhook event that you can receive using Request Bin.

To start, log in to your agency's beta environment Terminal.

  • If you aren't sure what your Terminal URL is or whether or not you have access, contact your agency's point of contact for your partnership with Bold Penguin.

After logging in to your beta environment Terminal, create a new Application Form.

After creating a new Application Form, follow the prompts and enter in information. You can use the same information as in the screenshots below. After entering information on each screen, click the next button.

At this point you will be asked to enter additional information that is specific to an individual carrier. Enter generic details and then continue to click the next button.

Finally, select save and close.

Once you have completed creating an application form, navigate to Request Bin or open your Request Bin tab and select the workflow that you created previously.

If you have completed the steps, you'll notice one or more HTTP POST events in the menu. You can select any of these events to expand the details to see the delivered webhook event.

Questions?

For general troubleshooting, check out our Troubleshooting Guide.

For additional questions please contact our developer support team: devsupport@boldpenguin.com