README.md

HookStack

This app/service was created because I wanted to use webhooks with self-hosted apps and did not want the requirements of installing agents, opening firewall ports or needing a static IP and having the system be available 24/7 to ensure no webhooks are missed. There are many services (free and chargeable) that provide a webhook relay service, but the ones I looked at just relayed the information to another webhook, which did not solve my problem.

This service allows webhooks to be Pushed (submitted) and saved, and then Pulled (retrieved) at any time in the future. The webhooks can be tagged with a source system identifier (source-id), and then downloaded by source system, this allows different processes or tools to download the webhooks from specific systems.

This service can also be used with some cloud hosted automation services that do not allow webhooks but do allow scheduled get requests (e.g., Microsoft Power Automate).

---

Environment Variables

To run this code, you will need to provide following environment variables, you will be prompted automatically when using Deta Space.

DETA_PROJECT_KEY - automatically populate when deployed to Deta Space

API_KEY - you can use anything or generate something 'secure' at keycdn Tools

---

Deploy to Deta Space

Deta Space

You can configure the required API key in app settings. All data will be private in your own account.

---

API Reference

Post Webhook

  POST /p

Parameter	Type	Description
source	string	Optional but Recommended. Source System Key, can be anything you want or left blank .

All data is stored in your Deta Space account in a Deta Base called 'HookStack'. This means your data is not available for me or anyone else to see, but do not forget it is only protected by your API key. Your API Key is not required to post data.

Example

  POST /p?source=system-name
  BODY {
        "value1": "a-to-z",
        "value2": "1-to-9",
        "value3": "500"
        }

The BODY data can be in any format, with as many or as few fields as you want. The service will reply in the following format.

  RESPONSE 200
  BODY {
          "success": "data received",
          "key": 1628781752490,
          "body": {
            "value1": "a-to-z",
            "value2": "1-to-9",
            "value3": "500"
          },
          "source": "system-2"
        }

This response is what is stored in the Deta Base:

Parameter	Type	Description
key	string	This is automatically generated with a UNIX Timestamp.
body	JSON	This is the body of your POST, no validation or modification is performed.
source	string	This is the key used to collate the webhooks that are stored. If this field is left blank (not recommended) when posting, it will be modified to 'unknown'.

---

Get items for source system by id

  GET /webhooks/$source

This will return all webhooks from the system with a matching source key and delete all corresponding results from the Deta Base by design to minimise the length of time your data is stored online.

Parameter	Type	Description
api-key	string	Required. Your API key

Example Response

  GET /webhooks/system-2?api-key=verysecure
  BODY
  {
      "items": [
          {
              "body": {
                  "value1": "a-to-z",
                  "value2": "1-to-9",
                  "value3": "500"
              },
              "key": "1628782459290",
              "source": "system2"
          },
          {
              "body": {
                  "value1": "a-to-z",
                  "value2": "1-to-9",
                  "value3": "500"
              },
              "key": "1628782460100",
              "source": "system2"
          }
      ]
  }

The webhooks received are returned in an array called 'items', this means they can be processed through another application.

Get items for source system unknown

  GET /webhooks

This will retrieve all webhooks posted without a source key, it will also delete all corresponding results from the database by design.

Parameter	Type	Description
api-key	string	Required. Your API key

The responses are the same as the above request with the included system-id.

---

Feedback

If you have any feedback, you can:

or

---

Acknowledgements

This was a sample app, used as my starting point. ExpressJS Example - Simple Web API