handcraftedbits/nginx-unit-webhook repository overview

⁠NGINX Host Webhook Unit

A Docker⁠ container that provides a webhook unit for NGINX Host⁠.

Webhooks are useful for creating an endpoint that, when accessed, runs a command on the server hosting the webhook. This is commonly used by REST APIs as a way to subscribe to an event. For example, GitHub⁠'s APIs can call a webhook whenever a push has been made to a Git repository.

This container makes use of adnanh/webhook⁠ to create webhooks.

⁠Features

• adnanh/webhook 2.6.2

⁠Usage

⁠Configuration

It is highly recommended that you use container orchestration software such as Docker Compose⁠ when using this NGINX Host unit as several Docker containers are required for operation. This guide will assume that you are using Docker Compose.

To begin, start with a basic docker-compose.yml file as described in the NGINX Host configuration guide⁠. Then, add a service for the NGINX Host webhook unit (named webhooks):

webhooks:
  image: handcraftedbits/nginx-unit-webhook
  environment:
    - NGINX_UNIT_HOSTS=mysite.com
    - NGINX_URL_PREFIX=/webhooks
  volumes:
    - data:/opt/container/shared
    - /home/me/webhooks.json:/opt/container/webhooks.json

Observe the following:

• We mount /opt/container/webhooks.json using the local file /home/me/webhooks.json. This is a file containing our webhook configuration. Refer to the documentation⁠ for information on the contents of this file.
• As with any other NGINX Host unit, we mount our data volume, in this case named data, to /opt/container/shared.

Finally, we need to create a link in our NGINX Host container to the webhooks container in order to host the webhooks. Here is our final docker-compose.yml file:

version: "2.1"

volumes:
  data:

services:
  proxy:
    image: handcraftedbits/nginx-host
    links:
      - webhooks
    ports:
      - "443:443"
    volumes:
      - data:/opt/container/shared
      - /etc/letsencrypt:/etc/letsencrypt
      - /home/me/dhparam.pem:/etc/ssl/dhparam.pem

  webhooks:
    image: handcraftedbits/nginx-unit-webhook
    environment:
      - NGINX_UNIT_HOSTS=mysite.com
      - NGINX_URL_PREFIX=/webhooks
    volumes:
      - data:/opt/container/shared
      - /home/me/webhooks.json:/opt/container/webhooks.json

This will result in making the webhooks available at https://mysite.com/webhooks.

⁠Running the NGINX Host Webhook Unit

Assuming you are using Docker Compose, simply run docker-compose up in the same directory as your docker-compose.yml file. Otherwise, you will need to start each container with docker run or a suitable alternative, making sure to add the appropriate environment variables and volume references.

⁠Reference

⁠Environment Variables

⁠WEBHOOK_VERBOSE

Used to show verbose webhook logging (e.g., rule matching, command execution) if set to true.

Default value: false

⁠Others

Please see the NGINX Host documentation⁠ for information on additional environment variables understood by this unit.