# Welcome To Our Developer Resources ## Quick Links For You {% content-ref url="/pages/-MWksbZZubwGufgDl6uD" %} [Getting Started](/getting-started/what-is-hosted-hooks) {% endcontent-ref %} {% content-ref url="/pages/-MWl-zaLRs64sSsnlBKs" %} [Quickstart](/getting-started/quickstart) {% endcontent-ref %} {% content-ref url="/pages/-MYI3eFVD8Y5hzww5FV7" %} [API Object Definitions](/developer-resources/components) {% endcontent-ref %} # What is HostedHooks HostedHooks is a fast and easy way to build out a Webhooks service for your application. ## Intro HostedHooks is a webhooks as a service solution for software applications. We aim to handle all of the complexity that comes with building a reliable webhook sending solution and let your team focus on building and growing the service that is triggering those webhooks. ## Who Is HostedHooks For? HostedHooks was created to help software platforms / teams add event-driven architectures via Webhooks to their applications in a matter of days. Whether or not your team has the ability and experience to build out scalable Webhooks, they are not a small feat and often not a core focus for the business. We help these companies add a very popular piece of functionality without all the cost and in a fraction of the time. ## How HostedHooks Works HostedHooks is centered around two main types of users: * [Providers](/developer-resources/providers) * Subscribers **Providers** are the web application that want to send webhooks out for specific events that are triggered within their application. ([More on how we can help providers here](/developer-resources/providers)) **Subscribers** are the applications or users that want to receive the webhooks from an application based on certain events. Integrating with HostedHooks is primarily for web applications that want to be webhook **Providers**. They have an application that has regularly occurring events and want to notify their users (subscribers) of these events. The ideal way to do this is via Webhooks. There is a significant amount of work that goes into building out a custom Webhooks solution that is reliable, scalable and a good experience for your webhook subscribers. HostedHooks handles that all for you. We have created a platform that makes adding Webhooks to your application as easy as a few API calls. ## Support Our documentation is quite extensive, but won't cover everything. If you run into any issues, please reach out to us at . # Quickstart A quick walkthrough of HostedHooks and steps to getting started ### Getting Started 1. Start by signing up for a new account at . 2. Once logged in you will be prompted to add the name and email of your Organization or Company. The name will be used when you invite Subscribers to your webhooks. It's best if it is named something recognizable. 3. Once your account is created you will be presented with the **Getting Started** page which we will cover here. ![](/files/-McyLuMZwHCIppqxti8q) To help onboarding we go through the process of automatically setting up a demo instance within your account. This demo instance is comprised of a Demo App, Demo Webhook Event, Demo Subscriber and a Demo Endpoint. These four parts of the required components of a basic HostedHooks webhook account. We then will provide you with a sample cURL request (an example below) that you can copy and paste into your terminal to send a message via the API to this Demo App and trigger an outgoing Webhook Attempt. ```bash curl -XPOST -H 'Authorization: Bearer asd2sgg2iMh42JWbPNs' -H "Content-type: application/json" -d '{ "event_type":"user.created", "version":"1.0", "data":{ "note":"this is a test", "id":123123123, "other_id":1231231123 } }' 'https://www.hostedhooks.com/api/v1/apps/8f8ad1e0-229b-4773-9756-4292e4486a3f/messages' ``` Once that cURL request has been properly sent ( you should receive a 200 back ), you can click through to your dashboard and see the request you just sent. # Email Parsing Learn how to start parsing emails today ( no code required ) ## Introduction Email parsing is a valuable tool that can help businesses and individuals manage their email communications more efficiently and effectively. With an email parser, you can extract specific information from an email message and use it in a variety of ways, such as populating a database or spreadsheet, generating automatic responses, or triggering actions based on the information contained in the email. ## What You Will Build In this guide, we'll walk you through how our Email Parsing platform works and we'll show you how to set up a simple email parsing example. # Ingesting Emails Once you sign up for email parsing and land on your email parsing dashboard, you will see a custom email address that you can use to send emails to. This email address will receive your email, ingest it and store it to your account.
Go ahead and send a test email to your custom email address. Once you've done that head over to your inboxes (on the sidebar) and find the inbox that you just setup. There will be an inbound email request waiting for you. # Webhooks Add Webhooks to your app with a simple integration ## Introduction Whether you have an API or not, Webhooks have become the status quo for asynchronous API events. They enable your users to receive updates on events from your platform and remove the need to poll your API for changes. ## What You Will Build In this guide, we'll walk you through how Webhooks work and we'll proof of concept a working demo of your app sending out webhooks using the HostedHooks API. In this guide we'll show you how to: 1. Add Webhooks to your app 2. Setup your sender and recipient records 3. Trigger a webhook from your app and watch it be received by your subscriber ## Before Getting Started To get the most of out of this guide, you'll need: * A HostedHooks developer account #### API Object Definitions | Object | Definition | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | App | An App is an object that represents your application. It is also the object that will be sending webhooks and that your webhook recipients will subscribe to. | | Endpoint | A endpoint is an object that represents your subscriber's webhook destination. It provides all the attributes around what events and where to send the webhooks. | | Subscription | A subscription is the relationship between your webhook recipient's endpoint and your app. | | Message | A message is an object that represents the API call from your App to HostedHooks. The contents of a message get converted into a Webhook attempt. | # Setup Your App ## Overview Before we start coding, we need to setup some resources in the HostedHooks dashboard. Login to your dashboard and let's walk through setting up your App. ### 1. Generate an App Once in your dashboard, click **Setup New App**, fill out the App name and click Save. ![](/files/-Mflp9Ca19g4vM9mtjuV) ### 2. Setup a Webhook Event Next we will need to create a Webhook Event for your app that subscribers can subscribe to. Go ahead and click **Add More Events** on your app page which will take you to a form to create a new **Webhook Event**. Here you need to fill out: * Event Type - This is the name of the event that you send webhooks for. We recommend a naming convention of `namespace.event` like `user.created`. * Data Payload - This is a sample payload that your subscribers will be able to trigger during implementation to help them test their inbound webhooks integration. ![](/files/-MfmM4YEhSAy70RUXusK) ### 3. Add a Test Subscriber To test your HostedHooks integration we will want to see the end to end flow in action. In order to achieve this you will need to setup a test subscription which will simulate a real user that has subscribed to your webhooks. Go ahead and click **Add A Subscriber** and enter a name for your subscriber. This will be a test so the name doesn't matter. The view that you get redirected to is what your Subscriber's will see when they login. ![](/files/-MfpCBzEkWvMv5D-zyXg) Now that we have a subscriber we will need to setup an endpoint for them. ### 4. Create An Endpoint Endpoints are the objects that hold all of the metadata around delivery, security and routing of your webhooks. In production you can either create these for users or give them access to create their own. For this demo, we'll go ahead and create an endpoint for our test subscriber. Get started by clicking **Setup New Endpoint**. {% hint style="info" %} When setting up your endpoint URL, you will need to use a public URL that can be accessed via the open internet. If you are on your development environment, localhost (by default) will not be public so you will need to make it public. We recommend you use a platform like [Ngrok](https://ngrok.com). Ngrok will allow you to easily make your localhost publicly available so HostedHooks can reach it successfully. It's very easy to use and we use it internally here at HostedHooks. {% endhint %} #### Endpoint Data | Field | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | URL | This URL is where we will send the webhook messages. If this URL does not return a 200 we will retry until it fails. In production this needs to be an endpoint on your subscriber's application. For testing we recommend you use a HookHelpers webhook sandbox URL. | | Description | A text field describing what your endpoint is doing. This will help you organize your endpoints if you have multiple. | | Status | Endpoints can be in an active (default) or inactive state. Inactive endpoints will not receive webhook attempts. If an endpoint fails to return a 200 after all attempted retries, then the endpoint will be moved into an inactive state and both the provider and subscriber will be notified via email. | | Version | This is the version of the webhook message that this endpoint has subscribed to. As new versions get rolled out, this version maintains compatibility. | Once you have filled out all of the data hit save and your endpoint will have been created. Last up we need to subscribe our endpoint to webhook events. ![](/files/-Mfs4qE_xFZ05GsgNAAQ) ### 5. Subscribe To Events In order for your endpoint to start receiving messages, we need to tell it what events we want to subscribe to. On your endpoint page, you will see a list of available events that you can subscriber to ( we created this one is Step 2) under the **Subscribed Events**. Go ahead and pick the event that we created and click **Add Event**. This will subscribe your endpoint to this event and will allow it to start receiving messages for the **user.created** event. ![](/files/-MfwsJPnZtBF_xN4_Rrs) We are all done with the setup on the HostedHooks platform and now will move to building your API integration with HostedHooks. # Integrate With Your App ### Overview Now that your HostedHooks instance has been setup ([previous step](/getting-started/webhooks/setup-your-app)), 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. # Tasks `Tasks` in HostedHooks are designed to handle background jobs efficiently and seamlessly. They serve as the backbone for processing events and operations that don't need to be executed immediately within your application but are crucial for its functionality. You send HostedHooks a Task via the API, we ingest it, queue it and once it is done processing, we send it back to your application using webhooks. The `Task` object has a `payload` attribute which is a JSON blob that can you can customize as needed. The data that you add to the payload will get sent back to your application via Webhooks once it is done processing. You also have the ability to have your tasks run immediately or schedule them to run at some point in the future.\ \ Lets's walk through how to use them. # Getting Started ### Introduction Welcome to the HostedHooks Tasks feature! This guide will walk you through creating and managing tasks via our API. These tasks are designed to handle background jobs efficiently, allowing you to schedule and process crucial operations for your application. ### Prerequisites * An active account on HostedHooks. * API Key for authentication ([found here](https://hostedhooks.com/tasks_dashboard)). * Basic knowledge of API requests (e.g., using `curl`). ### Step 1: Understanding the Task Object * **event\_type**: A string to label your task. Must match your webhook endpoints in the dashboard. * **scheduled\_run\_time**: An optional ISO8601 timestamp to schedule tasks. Leave blank for immediate execution. * **data**: A JSON blob containing data for your task. This data is sent back to your application upon task completion. For example this could be the first name and email of a user that you need to send an email to. ### Step 2: Setting Up Your Environment * Ensure you have `curl` installed, or use any API client of your choice. * Have your HostedHooks API key at hand for authorization. ### Step 3: Creating a Task 1. Construct your API request: * URL: `POST https://hostedhooks.com/api/v1/apps/:app_uuid/tasks` * The app\_uuid is the ID of an app within your HostedHooks instance. * Headers: * `Authorization: Bearer YOUR_API_KEY` * `Content-Type: application/json` * Data: A JSON object with `event_type` (required), `scheduled_run_time` (optional), and data `(required)`. 2. Use the following `curl` command template: ```sh curl -XPOST \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H "Content-type: application/json" \ -d '{ "event_type": "your.event.type", "scheduled_run_time": "YOUR_SCHEDULED_TIME", // Optional "data": { // Your JSON payload } }' 'https://hostedhooks.com/api/v1/apps/:app_uuid/tasks' ``` 3. Replace `YOUR_API_KEY`, `your.event.type`, `YOUR_SCHEDULED_TIME`, and the JSON payload `data` with your specific details. ### Step 4: Handling Responses * Upon successful task creation, the API returns a JSON response with details like task ID, event type, status, and more. * Example response: ```json { "id": "unique-task-id", "event_type": "your.event.type", "status": null, "scheduled_run_time": "YOUR_SCHEDULED_TIME", "endpoint_id": null, "created_at": "timestamp", "data": { // Your JSON payload } } ``` ### Step 5: Monitoring and Debugging * Check the status of your tasks in the HostedHooks dashboard or via the API * Use the task ID from the response for any troubleshooting or support requests. ### Additional Tips * Ensure your `event_type` matches exactly with what's configured in your dashboard. * For scheduled tasks, verify the timezone and format of your `scheduled_run_time`. ### Conclusion You're now ready to integrate HostedHooks Tasks into your application. For any additional questions or feedback, please reach out to our support team. # Our Policy Keeping your data safe is one of the most important things that we do at HostedHooks. It is a part of our DNA and we take it very seriously. We are constantly working on new ways to provide additional security features and want to make sure you feel like you are in good hands. We've documented our [Security Policy here](https://hostedhooks.com/security) # Security Features Every application has a basic set of security needs and then depending on your industry, those requirements can become quite lengthy. We've taken the approach to start with a baseline of common security features for all users, that will come with all plans. We understand that not all applications will want to require strict security features and for that reason we've made some of the more advanced features optional. Features: * [Encryption](/security/security-features/encryption) * [Webhook Signatures](/security/security-features/webhook-signatures) # Encryption When it comes to storing or transmitting data, encryption is a requirement for all users of HostedHooks. We ensure this with the following: * We use strong encryption methodologies to protect subscriber data, including AES-256 encryption for subscriber data stored in HostedHook's production environment. * We store as much data as we operationally can, encrypted at rest. * We transmit all data using industry-standard AES-256 encryption. API endpoints can only be accessed via HTTPS. # Webhook Signatures Use Webhook Signatures to verify webhook events are coming from HostedHooks Each webhook event is sent with a header `HTTP_HOSTEDHOOKS_SIGNATURE`containing a signature and timestamp. These can be used together with your endpoint secret to compare signatures and confirm that the webhook event you are receiving came from HostedHooks. #### Prevent Replay Attacks Replay attacks are when an attacker intercepts a webhook message and resends it to the endpoint. We help mitigate this by adding a timestamp into the `HTTP_HOSTEDHOOKS_SIGNATURE` for you to compare with. We use this timestamp to sign the payload, so the attacker would not be able to change the timestamp without invalidating the payload signature as well. In the case where the payload signature is valid, but the timestamp is too old, you can choose to reject the webhook. We generate a new timestamp and signature when webhook messages are sent to the subscriber's endpoint. In the case of retries (where a previous webhook attempt returned a non 200 response), we will generate a new timestamp and signature. #### HostedHooks Signature Verification HostedHooks webhook messages will be sent with a `HTTP_HOSTEDHOOKS_SIGNATURE` that contains both a payload signature `s=` and a timestamp `t=`. ``` t=1623436092, s=7e526f3c14539d4d2856a1a2e8b1112c944cd466670041fe758fcc930d8cdf23 ``` {% hint style="info" %} New lines have been added here to make it more readable, but the actual `HTTP_HOSTEDHOOKS_SIGNATURE`is on one line. {% endhint %} #### Step 1: Parse the timestamp and signatures from the header Split the header using the `,` to get both the `s` and `t` values. Then use the `=` to split the keys from the value. The `s` value corresponds to the payload signature and the `t` value corresponds to the timestamp. #### Step 2: Create the signed\_payload To create the signed payload you will want to concatenate the following values * The timestamp * the character `.` * The JSON payload received (request body) #### Step 3: Generate the expected Signature Generate an HMAC with the SHA256 hash function. The key for the hash function is your endpoints signing secret and the `signed_payload` string is the message. #### Step 4: Compare the signatures Compare the signature that you received in the header (Step 1) with the generated signature (Step 3). If those match, then calculate the difference between the current timestamp and the received timestamp (step 1) and determine if the difference is within an acceptable tolerance. {% hint style="info" %} Use a constant time string comparison to compare the generated signature with the received signature. This will protect against timing attacks. {% endhint %} # API Object Definitions A high level review of the API objects that make up the HostedHooks platform. ## API Objects * [Organization](/developer-resources/components/organization) * [Apps](/developer-resources/components/apps) * [Subscriptions](/developer-resources/components/subscriptions) * [Endpoints](/developer-resources/components/endpoint) * [Webhook Events](/developer-resources/components/webhook-events) * [Messages](/developer-resources/components/messages) * [Webhook Attempts](/developer-resources/components/webhook-attempts) # Organization The details of what an Organization is and how it's used ## What Are Organizations? An organization is simply the record that stores all of the details relevant to your company. It is the highest level resource and everything under it will belong to your organization. This includes Users, Apps, Subscriptions, etc. # Apps The details of what an App is and how it's used ## What Are Apps? An App is your software application where events are occurring that you want to notify your subscribers of. When events occur on your application, you will be sending those to HostedHooks via a POST Message API call. \ \ When your users subscribe to your Webhooks via HostedHooks they will be subscribing to your App, so it's important that it is named something that they will recognize. # Subscription The details of what a Subscription is and how it's used ## What Are Subscriptions? A Subscription is an Organization subscribing to your App's webhook messages. Your App will have many subscribers via their Subscription resource. # Endpoint The details of what an Endpoint is and how it's used ## What Are Endpoints? An Endpoint is where your App's Subscribers will define where they want to receive the webhook messages. The Endpoint has the following parameters: * URL * Description * Version #### URL This is a full URL with the protocol, domain and path (example below) to where your Subscriber wants to receive their webhook messages. ``` https://hostedhooks.com/r/a2ad45asafa2asad998asf ``` #### Description A way to organize your endpoints with a simple text description. ![](/files/-MYIORxUOeI6mvVhNENL) #### Version This is a custom string that denotes what version of the webhook the specific Endpoint is configured for. This number allows the providers to upgrade webhook payloads without breaking the existing Endpoint implementations. Your subscribers will only be able to select from existing versions. ![](/files/-MYIObOHfrnAqXZBDyEY) # Webhook Events The details of what a Webhook Events is and how they are used ## What Are Webhook Events? A webhook event are the specific events that a webhook provider will be sending webhooks for. Subscribers to a webhook will choose any or all webhook events they want to subscribe to. # Messages The details of what a Message is and how they are used ## What Are Messages? A message is the payload that your application will send to HostedHooks via the API when an event gets triggered. A message payload will look something like this: ```javascript { "version" : "1.0", "event_type": "user.created", "event_id": "12323124151", "data": { "foo": "bar" } } ``` The Message has the following parameters: * Version * Event Type * Event ID * Data # Webhook Attempts The details of what a Webhook Attempt is and how they are used ## What Are Webhook Attempts? A Webhook Attempt is the outbound message from HostedHooks to your subscriber's endpoint. If the Webhook Attempt is unsuccessful we will try for 5 attempts and then notify you that the Webhook Attempt failed. # Providers ### What are Providers? **Providers** are anyone that want to send webhooks from their web application out to subscribers. The webhooks are triggered by events (user created or order shipped) occurring on their platform. Providers can have as many HostedHooks apps as they like, with each app having many subscriber applications. These subscribers will have their respective endpoints which HostedHooks will use to deliver the webhook messages. ### Am I Provider? If your application has users that want to be notified when certain events occur then yes, you are provider. You would notify those users via webhooks. ### Provider Features HostedHooks was built to provide robust and production ready webhooks out of the box. To accomplish this we provide every feature required to start sending webhooks today. #### RESTful JSON API We've built a very simple to use RESTful JSON API to integrate HostedHooks into your application. With under 20 lines of code you can start sending webhook messages to your subscribers. We've also generated code samples in all of the popular languages and frameworks to help get you started. #### Provider Portal One of the huge benefits of going with a platform like HostedHooks is the user experience that we've built around managing Webhooks. If you were to build this yourself, all of the admin functionality ( logging, managing endpoints, viewing subscribers, inviting users, etc ) would need to be custom built. With HostedHooks, we've built all of that for you. Providers get a login and a dashboard where they can manage their applications, the webhook events they are triggering, all of their subscribers, view logs (success and failures) and much more. We know what it takes to manage webhooks and have give that you in an easy to use dashboard. #### Smart Retries & Endpoint Monitoring In the event that a susbcriber's endpoint is responding with a non 200 response, we will use our retry logic to make additional requests with an exponential backoff delay. This will eventually cap at a 5 attempts. Once this cap is met we will turn off the endpoint and we will notify both you the provider and the subscriber. Once the subscriber fixes the issue, they will be able to turn back on their endpoint and replay the missed webhook events, ensuring they don't miss any data. #### Logging All webhook attempts are logged for providers to search and filter by error/success statuses and subscribers. #### Webhook Signatures All webhooks are sent with a `HTTP_HOSTEDHOOKS_SIGNATURE` in the header that can be used to validate the payload and timestamp of the sent webhook. More info below. {% content-ref url="/pages/-McKFafS795ptrG6OHG2" %} [Webhook Signatures](/security/security-features/webhook-signatures) {% endcontent-ref %} # Managing Replays As a provider of webhook services, it's normal to encounter instances where your subscribers' endpoints become unresponsive occasionally. During these instances, your webhooks will persistently attempt to reestablish the connection until the retry failure count. At this point, HostedHooks will notify you and your subscribers (optional) via email about the failed webhook attempt. All records of failed webhook attempts are kept for your respective plan's log duration. Ensuring that you have the capability to replay the events is crucial, and there are two methods to achieve this. ### Manual replay On the subscription and endpoint pages you can manually replay individual failed webhook attempts by clicking the replay button under the payload.
### Bulk Replay On the endpoint page under the webhook attempts list you will see a "Replay Failed Attempts" button which will take you to a view where you can replay multiple webhook attempts at once.
Here you will receive a list of all failed webhook attempts for your endpoint. Use the date range to show all attempts since a certain point. Select the webhook attempts that you want to replay and click the replay button on the bottom. {% hint style="info" %} Replaying webhook attempts is asynchronous, so you will not see these update in real-time. Once you hit replay, give them a few minutes and check to see if they were successful. {% endhint %}
### Duplicate Replays On this view you may notice a green check mark next to the `event id` of your webhook attempt. If this green check mark is present on a failed webhook attempt, it means that another webhook attempt (with the same event id) was already delivered successfully to your subscriber's endpoint. This gives you the option to send them again or ignore.
# Subscribers ### What are Subscribers? Webhook subscribers are individuals or organizations that have opted to receive updates from a particular provider through webhooks. These subscribers, who are typically the provider's customers or users of their platform, establish a subscription with the provider's application in order to receive webhooks. Each subscription allows the subscriber to specify one or more endpoints, or URLs, where they wish to receive webhooks for specific events. These events can range from simple notifications, such as a new user signing up, to more complex updates, such as a change in a user's account status. The subscriber can also manage their subscriptions and endpoints, for example by adding or removing them as needed. Through webhook subscriptions, subscribers can stay informed about important updates and changes from the provider's application in real-time, without the need to repeatedly check for updates. ### What can Subscribers do? As a webhook subscriber, you have several controls at your disposal to help manage your webhooks. These controls allow you to customize your subscription to suit your specific needs and preferences. Some of the key controls include: 1. Endpoint management: You can specify one or more endpoints, or URLs, where you wish to receive webhooks. This allows you to route webhooks to different systems or applications depending on the event. 2. Event selection: Providers allow you to choose the events you want to receive by adding them to your endpoint. For example, you may only want to receive webhooks for updates related to a specific user or account. 3. Authentication: Some providers may require you to use a signing secret or SSL to receive your webhook. This would be in the form of a secret token. 4. Retries and Error handling: Some providers may allow you to set retry policies or error handling options to ensure that webhooks are delivered successfully. 5. Notifications: Some providers may allow you to set whether you receive notifications for webhook events (failure notifications for example). These controls give webhook subscribers the flexibility and granularity to manage their webhooks, and to configure them to suit their specific needs and preferences. Webhooks provide an efficient and real-time way for subscribers to receive updates from the providers' applications, and these controls make them even more powerful. # Subscription Management As a webhook subscriber, you have access to a subscription view that provides a comprehensive overview of your webhook setup. This view gives you a bird's-eye view of all your endpoints, error rates, webhook attempts, and version status of the subscription. This allows you to easily monitor the performance and health of your webhooks, and take action when necessary. The subscription view allows you to see at a glance the status of your endpoints and webhooks, including the number of attempts made, the percentage of successful deliveries, and the percentage of errors. This information can help you identify potential issues, such as an endpoint that is not responding, and take steps to resolve them. Additionally, the version status of the subscription shows the version of the webhooks you are currently using, this way, you can ensure that you are always up-to-date with the latest features and functionality. This can be especially important when new features are released and you want to take advantage of them as soon as possible.
Within this view you can also **Setup New Endpoints** # Endpoint Management ### Create a New Endpoint As a webhook subscriber, you have the ability to create new endpoints to suit your specific needs. In order to create a new endpoint, you must provide certain information such as a URL, a default version, a description, and set the status of the endpoint. The URL is the address where the webhooks will be sent when the events occur, this is the destination where you want to receive the webhooks. The default version is the version of the webhooks that you want to receive by default, this way you can ensure that you are up-to-date with the latest features and functionality. A description of the endpoint can help you identify the endpoint more easily and keep track of what it is for. Finally, setting the status of the endpoint allows you to enable or disable it as needed, this is particularly useful when you need to temporarily disable an integration.
### View Your Endpoint View your endpoint to grab the endpoint ID, error rate, endpoint URL, signing secret, view and subscribe to webhook events and even send a sample payload for the event. \ \ As a webhook subscriber you have the ability to view your endpoint and access important information such as the endpoint ID, error rate, URL, signing secret, and more. This allows you to easily manage and keep track of your webhook subscriptions. The endpoint ID is a unique identifier that can be used to track and manage the endpoint. Additionally, you can see the error rate, which can help you identify if there are any issues with the endpoint that need to be addressed. You can also view the endpoint URL, which is the destination where the webhooks will be sent when the events get triggered. This can be useful if you need to check that the URL is correct or if you need to update it. Here you also have the ability to subscribe/unsubscribe to specific webhook events, this way you can ensure that you are only receiving the information that is relevant to you, and that it is delivered to the right place. Furthermore, you can even send a sample payload for the event to test your endpoint.
### View Endpoint Webhook Logs As a webhook subscriber, you also have the ability to view your webhook logs. This feature allows you to easily track and monitor the status of your webhooks, and troubleshoot any issues that may arise. You can filter the logs by different criteria such as succeeded or failed webhook attempts, event type, your unique event ID, error message, status code, or even the payload. This allows you to quickly and easily identify any webhooks that have not been delivered successfully, and to view the details of the specific error that occurred. The event type filter allows you to see the type of event that was triggered, this can be useful to understand the context of the webhook. The unique event ID filter is used to track the event across different systems and ensure that you are looking at the correct event. The error message filter allows you to see any error message that was generated during the webhook attempt, this can be useful to understand what went wrong and how to fix it. Additionally, the status code filter allows you to view the status code that was returned by the webhook, this can be useful to understand the outcome of the webhook attempt. The payload filter allows you to view the payload that was sent during the webhook attempt, this can be useful to understand the data that was sent and check if it was the right data.
# Internal Webhooks Learn how to receive webhooks from HostedHooks whenever a new subscriber signs up for your webhooks {% hint style="info" %} This feature is being rebuilt to support more notification types. Please reach out to if you are interested in it. {% endhint %} ## Introduction As a provider you'll want to receive updates when your subscribers take certain actions with your webhooks. These are things like "user subscribes to your webhooks" or "user creates a new endpoint". When these actions occur, you can get notified by becoming a subscriber of the HostedHooks Provider webhooks. We will send a webhook message to your endpoint to help generate mappings and maintain state. Let me walk you through how to do that. ## Getting Started ### Step 1: Create an account Before you can subscribe to the HostedHooks internal webhooks, you will need to create an account. You can do that by heading over to . ### Step 2: Get Invited Once you have an account you will need to be invited to our internal webhooks. Reach out to and we will get you setup. If you don't already have an account then you will receive an email inviting you to set one up. ![](/files/-Mh13UysNNoSKVWR_M3x) ### Step 3: Setup your endpoints Once you accept the invitation and setup your account ( if not already created ) you will see a section where your subscriptions are listed. The subscription will be called "HostedHooks Providers". Click "View" on your subscription to start creating your endpoints. To do so you will need to add your endpoint URL, a description and leave the status on active. Once your endpoint is created, make sure you pick the events that you want that endpoint to receive. ![](/files/-Mh1DK84c1ES56o-TZQM) ### Step 4: Ingest webhook payload #### Supported Events | Event Name | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `subscriber.created` | Whenever a subscriber is created you will receive a webhook (payload below) with all of the relevant data to maintain a mapping on your system. | We currently support the `subscriber.created` (let us know if you need a different event) webhook event which will get triggered whenever you have a new subscriber signs up for your webhooks. This will allow you to keep track of the subscriber ID so you can trigger your webhook messages to the correct subscriber. This is what the `subscriber.created` webhook payload will look like. ```javascript { "data": { "subscription": { "id": "166213ab-a480-4ab3-9868-7ac3359ea63a", "status": "active", "updated_at": "2021-03-29T10:03:09.717-04:00", "created_at": "2021-03-29T10:03:09.717-04:00", "organization": { "id": "166213ab-a480-4ab3-9868-7ac3359ea63a", "name": "ABC Company", "updated_at": "2021-03-29T10:03:09.717-04:00", "created_at": "2021-03-29T10:03:09.717-04:00", "email_address": "support@abccompany.com" } } }, "version" : "1.0", "event_type": "subscription.created", "event_id": "12323124151", "created" : "2021-08-12T03:49:44.837Z" } ``` Once you've subscribed to this payload, you will be able to trigger sample payloads from your endpoint page which will send mock webhook attempts to your endpoint URL. ![](/files/-Mh15gGxa249XXMOImEf) The webhook attempt will be sent as a POST request and the response must return a 200 or it will be assumed they have failed and the webhook attempts will be retried until a 200 response is received. If you are interested in verifying the signature on your webhooks, you can follow [this guide here](https://docs.hostedhooks.com/security/security-features/webhook-signatures) on how to use the HTTP\_HOSTEDHOOKS\_SIGNATURE. ### Step 5: Go live Once you are comfortable with how your webhooks are being ingested, you are all set and are ready for production. There is nothing left for you to do except to start adding subscribers to your webhooks. ## Conclusion If there are any other events that you want to receive, please let us know and we will work to add them. And as always, we are here to help with your integration. If you have any questions please reach out to