> For the complete documentation index, see [llms.txt](https://docs.hostedhooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostedhooks.com/getting-started/webhooks/integrate-with-your-app.md).

# Integrate With Your App

### Overview

Now that your HostedHooks instance has been setup ([previous step](/getting-started/webhooks/setup-your-app.md)), 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.

```bash
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](https://www.hostedhooks.com/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. 

![](/files/-Mg0jhCajIOHn0PQERua)

### 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](https://developers.hostedhooks.com/#create-a-message-app). The URI for that endpoint is below. It has one parameter, the `app_id` which you copied from the dashboard in the previous step. 

```bash
"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. 

{% hint style="info" %}
If you need to send webhooks to a specific subscriber's endpoint, you can use the API endpoint [documented here](https://developers.hostedhooks.com/#create-a-message-endpoint). 
{% endhint %}

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. 

{% tabs %}
{% tab title="Ruby" %}

```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
```

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}

{% tab title="Laravel" %}

```php
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()]);
    }
  }
}
```

{% endtab %}

{% tab title="Javascript" %}

```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));
}
```

{% endtab %}
{% endtabs %}

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

```javascript
{
  "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. 


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hostedhooks.com/getting-started/webhooks/integrate-with-your-app.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.