Build Webhooks using PHP and HostedHooks June 2021 · ian

Introduction

In this post we'll walkthrough how to implement HostedHooks - Webhooks as a Service using vanilla PHP code. If you are using a PHP framework, like Laravel, you can view the Laravel specific walkthrough here - HostedHooks Laravel Walkthrough

Before you get started with your API integration, you will need to first setup your HostedHooks instance. This will give you the requisite ids and setup the test endpoint that you will be sending your webhook messages to.

We cover that setup in this post - How To Setup Your HostedHooks Instance

If you have already setup your instance, you can skip that and continue on with this PHP implementation.

We will walk through how to use PHP to construct the API calls needed to send Webhook messages to your susbcribers.

API Setup

Every HostedHooks API call requires your API_KEY, which can be found in your settings here.

We'll reference that API key in the examples with this variable.

HOSTEDHOOKS_API_KEY

Ideally this should be set as an environment variable which you will need to setup in your PHP configuration.

Now that we have our API key we need to grab some data for the API call. In the example below we will be sending a webhook message whenever a new user has been created. I've setup this webhook event on the HostedHooks platform and labeled it as 'user.created'.

There are two ways to send webhook API calls:

1. Send the message to the app level, which will notify all subscribers of that app that are also subscribed to the specific webhook event that was triggered (user.created in our case). This method is easy, but may not work if you need to send record specific data to your subscribers. If that is the case you should use the 2nd method.
2. Send the message directly to an endpoint, which will notify only the subscriber of that endpoint. This method is much more direct, but requires you to map subscriberid and endpointid to your users.

We'll walk through both examples and then move on to the sample code.

Method 1: Send a Message to an App

For this API call we will be sending a POST request to the messages (app) API but will be targeting a specific app. To make this call we'lll need the App UUID that we want to send the message to. You can copy that UUID by heading to your dashboard, clicking on the App that you want to use and copying the UUID at the top of the page.

We will need to take that App UUID and pass it into the Messages API URL which will look like this:

https://www.hostedhooks.com/api/v1/apps/:app_uuid/messages

If you need to send subscriber specific data inside your webhook message than this next method is likely the route you will want to take.

Method 2: Send a Message to an Endpoint

For this API call we will be sending a POST request to the messages (endpoint) API, but will be targeting a specific endpoint. To make this call we will need the Subscription UUID for the Subscriber and the respective Endpoint UUID which defines where we will send the message to. You can copy that UUIDs by heading to your dashboard, clicking on the Subscriber that you want to use and copy the UUID at the top of the page.

We will need to take that Subscription UUID and Endpoint UUID and pass it into the Messages API URL which will look like this:

https://hostedhooks.com/api/v1/subscriptions/:subscription_uuid/endpoints/:endpoint_uuid/messages

Now that we have all of the data required for the API call, let's walk through the code.

Setting Up The Code

Lastly, we will want to update the data object (JSON) which is being sent. In PHP this is an associative array, rather than an object. You are free to put whatever you want inside that array and we will pass everything inside it onto your subscribers. For the sake of this example we will add a nested user array and add some user data.

$messagePayload = [
  'data' => [
    'user' => [
      'id' => $user['id'],
      'created_at' => $user['created_at'],
    ],
  ],
  'version' => '1.0',
  'event_type' => 'user.created',
  'event_id' => '07a1cf3fd7cced67a7fd',
];

Outside of the array there are a few additional parts of the message payload, let's go through them here:

• version - This is the version of the payload that you are sending (more info here)
• 'eventid' - This is a unique string that HostedHooks will check to maintain idempotency. We will ignore multiple requests with the same eventid. You should generate this on your end and can store this if you wanted to.
• event_type - This is the event that you are sending webhooks on behalf of (user.created in our case)

Once you've constructed your request payload, you can now make the request using whatever HTTP library you want. In our example we've used the native PHP cURL library. See the example request below.

Note: we have provided two URIs, one for each method of sending messages. You would need to pick which one suits your usecase.

Below is the code to make a POST request to the HostedHooks API using PHP.

function sendWebhookMessage($user)
{
  $apiKey = "your-api-key";

  /* Method 1 - Send message to App*/
  $uri = "https://www.hostedhooks.com/api/v1/apps/{app_uuid}/messages";

  /* Method 2 - Send message to Endpoint */
  $uri =
    "https://hostedhooks.com/api/v1/subscriptions/{subscription_uuid}/endpoints/{endpoint_uuid}/messages";

  /* Build message payload*/
  $messagePayload = [
    'data' => [
      'user' => [
        'id' => $user['id'],
        'created_at' => $user['created_at'],
      ],
    ],
    'version' => '1.0',
    'event_type' => 'user.created',
    'event_id' => '07a1cf3fd7cced67a7fd',
  ];

  $headers = array(
    'Content-Type: application/json',
    'Authorization: Bearer ' . $apiKey,
  );

  $ch = curl_init($uri);

  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);

  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($messagePayload));

  $response = curl_exec($ch);

  if ($response === false) {
    return [
      'status' => curl_getinfo($ch, CURLINFO_HTTP_CODE),
      'error' => "CURL Error: " . curl_error($ch),
    ];
  }

  return [
    'status' => curl_getinfo($ch, CURLINFO_HTTP_CODE),
    'body' => json_decode($response, true),
  ];
}

If that request is succesful you will get back a 200 and JSON response like below.

{
  "id": "4e4fffcb-295b-4b79-cda3-02cc4720f0ba",
  "data": {
    "user": {
      "id": 123,
      "created_at": "2021-05-11T08:51:40.679-04:00"
    }
  },
  "event_id": "07a1cf3fd7cced67a7fd",
  "event_type": "user.created",
  "created_at": "2021-05-11T08:51:40.679-04:00",
  "app": {
    "id": "bf111747-9635-46fb-as23-9b6e45402f47",
    "name": "SaaS Site",
    "created_at": "2021-03-31T21:24:48.376-04:00"
  }
}

Once that request has been made and the message is sent to HostedHooks, it will be processed and routed to the correct subscribers. If there are any deliverabiliy issues, we will retry (with exponential backoffs) for a total of 5 times and then notify you if that still fails.

You can view your deliverability stats in your Provider dashboard.

We hope this tutorial has been helpful and shows you how simple it is to get HostedHooks webhooks implemented.