README.md

Webhooked

A webhook receiver on steroids. The process is simple, receive webhook from all over the world, and send it to your favorite pub/sub to process it immediately or later without losing any received data

Motivation

When you start working with webhooks, it's often quite random, and sometimes what shouldn't happen, does. One or more data sent by a webhook is lost because our service did not respond, or worse to crash. That's why very often it's better to make a small HTTP server that only receives and conveys the information to another service that will process the information.

This is exactly what Webhooked does !

Roadmap

I am actively working on this project in order to release a stable version for 2025

Usage

Step 1 : Configuration file

apiVersion: v1alpha1
# List of specifications of your webhooks listerners.
specs:
- # Name of your listener. Used to store relative datas and printed on log
  name: exampleHook
  # The Entrypoint used to receive this Webhook
  # In this example the final url will be: example.com/v1alpha1/webhooks/example
  entrypointUrl: /webhooks/example
  # Security factories used to verify the payload 
  # Factories is powerful and very modular. This is executed in order of declaration
  # and need to be ended by a `compare` Factory.
  #
  # In this example we get the header `X-Hook-Secret` and compare it to a static
  # value. If the header value is equals to `test`, `foo` or `bar`, or the value
  # contained in SECRET_TOKEN env variable, the webhook is process. 
  # Else no process is handled and http server return a 401 error
  #
  # If you want to use insecure (not recommended), just remove security property
  security:
  - header:
      inputs:
      - name: headerName
        value: X-Hook-Secret
  - compare:
      inputs:
      - name: first
        value: '{{ Outputs.header.value }}'
      - name: second
        values: ['foo', 'bar']
        valueFrom:
          envRef: SECRET_TOKEN
  
  # Formatting allows you to apply a custom format to the payload received
  # before send it to the storage. You can use built-in helper function to
  # format it as you want. (Optional)
  #
  # Per default the format applied is: "{{ .Payload }}"
  # 
  # THIS IS AN ADVANCED FEATURE :
  # Be careful when using this feature, the slightest error in format can
  # result in DEFFINITIVE loss of the collected data. Make sure your template is
  # correct before applying it in production.
  formatting:
    templateString: |
      {
        "config": "{{ toJson .Config }}",
        "metadata": {
          "specName": "{{ .Spec.Name }}",
          "deliveryID": "{{ .Request.Header | getHeader "X-Delivery" | default "unknown" }}"
        },
        "payload": {{ .Payload }}
      }

  # Storage allows you to list where you want to store the raw payloads
  # received by webhooked. You can add an unlimited number of storages, webhooked
  # will store in **ALL** the listed storages
  # 
  # In this example we use the redis pub/sub storage and store the JSON payload
  # on the `example-webhook` Redis Key on the Database 0
  storage:
  - type: redis
    # You can apply a specific formatting per storage (Optional)
    formatting: {}
    # Storage specification
    specs:
      host: redis.default.svc.cluster.local
      port: 6379
      database: 0
      key: example-webhook


  # Response is the final step of the pipeline. It allows you to send a response
  # to the webhook sender. You can use the built-in helper function to format it
  # as you want. (Optional)
  #
  # In this example we send a JSON response with a 200 HTTP code and a custom
  # content type header `application/json`. The response contains the deliveryID
  # header value or `unknown` if not present in the request.
  response:
    formatting:
      templateString: |
        {
          "deliveryID": "{{ .Request.Header | getHeader "X-Delivery" | default "unknown" }}"
        }
    httpCode: 200
    contentType: application/json

More informations about security pipeline available on wiki : Configuration/Security

More informations about storages available on wiki : Configuration/Storages

More informations about formatting available on wiki : Configuration/Formatting

Step 2 : Launch it 🚀

With Kubernetes

If you want to use kubernetes, for production or personnal use, refere to example/kubernetes:

https://github.com/42Atomys/webhooked/tree/main/examples/kubernetes

With Docker image

You can use the docker image atomys/webhooked in a very simplistic way

# Basic launch instruction using the default configuration path
docker run -it --rm -p 8080:8080 -v ${PWD}/myconfig.yaml:/config/webhooked.yaml atomys/webhooked:latest
# Use custom configuration file
docker run -it --rm -p 8080:8080 -v ${PWD}/myconfig.yaml:/myconfig.yaml atomys/webhooked:latest serve --config /myconfig.yaml

With pre-builded binary

./webhooked serve --config config.yaml -p 8080

To-Do

TO-Do is moving on Project Section: https://github.com/42Atomys/webhooked/projects?type=beta

Contribution

All pull requests and issues on GitHub will welcome.

All contributions are welcome :)

Thanks