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!

Prerequisites​

  • Bold Penguin will provide you with a unique Client ID and Client Secret for your beta environment 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.

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

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-49b39116e023",
  "info": {
    "name": "First Name + Last Name",
    "email": "demo@domain.com",
    "first_name": "First Name",
    "last_name": "Last Name",
    ...
  }

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. This will typically be your own webserver or application which will receive the webhook events.

For this guide we will use Request Bin to demonstrate, which will require creating an account. Note that Request Bin is not suitable for production applications.

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": "ee224fd1-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-5429-q80b-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