Integrate With Your App

Overview

Now that your HostedHooks instance has been setup (previous step), we are now ready to start integrating HostedHooks into your App.

1. Pick your programming language

The HostedHooks API can be used easily with most programming languages. We will add code samples for several of them in this guide.

• Ruby

• PHP

• Javascript

• Laravel

2. Set environment variables

The HostedHooks API key is required for all API requests. It should be kept secret and set as an environment variable.

HOSTEDHOOKS_API_KEY='VdaYqFdqwrtqmQr6tJTuEBF1'

3. Copy your App identifier

Before we jump into the code we will need to grab your App identifier (ID) from the HostedHooks dashboard. Once at your dashboard, click View on your App and then click the copy icon to grab the unique ID of your app object.

3. Send a webhook message

In this step we will walk through how you trigger sending webhooks from your app.

The endpoint to send messages is documented here. The URI for that endpoint is below. It has one parameter, the app_id which you copied from the dashboard in the previous step.

"https://www.hostedhooks.com/api/v1/apps/:app_id/messages"

In addition to the app_id, the event_type is used to determine which subscribers will receive your webhook messages.

If you need to send webhooks to a specific subscriber's endpoint, you can use the API endpoint documented here.

The data object within the message payload is an open JSON object that allows you to pass in any information that you want. The data inside this payload will be passed on to your subscribers via the webhook endpoint they setup.

Ruby

def send_webhook_message()
  uri = URI("https://www.hostedhooks.com/api/v1/apps/:app_uuid/messages")

  headers = {"Content-Type": "application/json", "Authorization": "Bearer #{ENV['HOSTEDHOOKS_API_KEY']}"}

  # Build message payload
  message_payload = {
    data: {
        user: {
          id: "1337", 
          notes: "foobar"
        }
      },
      version: "1.0",
      event_type: "user.created"
    }
  }

  # Create Request
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  request = Net::HTTP::Post.new(uri.request_uri, headers)
  request.body = message_payload.to_json

  # Send the request
  response = http.request(request)

  puts "Response HTTP Status Code: #{ response.code }"
  puts "Response HTTP Response Body: #{ response.body }"
rescue StandardError => e
  puts "HTTP Request failed (#{ e.message })"
end

PHP

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

  $uri = "https://www.hostedhooks.com/api/v1/apps/{app_uuid}/messages";

  /* Build message payload*/
  $messagePayload = [
    'data' => [
      'user' => [
        'id' => '1337',
        'note' => 'foobar'
      ],
    ],
    'version' => '1.0',
    'event_type' => 'user.created'
  ];

  $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),
  ];
}

Laravel

use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\RequestException;

class HostedHooksService
{
  public function sendWebhookMessage()
  {
    $uri = "https://www.hostedhooks.com/api/v1/apps/{app_uuid}/messages";

    /* Build message payload*/
    $messagePayload = [
      'data' => [
        'user' => [
          'id' => '1337',
          'notes' => 'foobar',
        ],
      ],
      'version' => '1.0',
      'event_type' => 'user.created',
    ];

    try {
      $response = Http::withToken(env('HOSTEDHOOKS_API_KEY'))
      ->post($uri, $messagePayload);

      //Throw exception if a client or server error occurred
      $response->throw();

      //Otherwise go ahead with successful response
      Log::info('Request sent successfully', [
    'Status code' => $response->status(),
    'Response body' => $response->body()
      ]);

    } catch (RequestException $e) {
      Log::error('HTTP Request Failed', ['message' => $e->getMessage()]);
    }
  }
}

Javascript

function sendMessage() {
  var url = new URL("https://www.hostedhooks.com/api/v1/apps/${app_uuid}/messages");

  var myHeaders = new Headers();
  myHeaders.append("Authorization", "Bearer HOSTEDHOOKS_API_KEY");
  myHeaders.append("Content-Type", "application/json");

  /* Build message payload  */
  var messagePayload = JSON.stringify({
    "data": {
      "user": {
        "id": "1337", 
        "notes": "foobar",
      }
    },
    "version": "1.0",
    "event_type": "user.created"
  });

  var requestOptions = {
    method: 'POST',
    headers: myHeaders,
    body: messagePayload,
    redirect: 'follow'
  };

  fetch(url, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log('error', error));
}

On a successful Message API request, you will receive back a 200 and a payload like the one below.

{
  "id": "4e4fffcb-295b-4b79-cda3-02cc4720f0ba",
  "data": {
    "user": {
      "id": '1337',
      "notes": "foobar"
    }
  },
  "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 you've received a successful response, you've successfully triggered a webhook call from your app. We will now review the subscriber side to receive the webhook you sent.