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.