Webhooks service
Deploy the service that delivers io.sign events to your webhook subscriptions
The webhooks service delivers io.sign events to the URLs in your webhook subscriptions, and serves the /v1/webhooks API. It runs separately from the io.sign backend, with its own image, its own migrations image, and its own database.
The webhooks service receives events from the io.sign backend through Redis, then signs, sends, and retries each delivery.
The webhooks service needs:
- Access to the same Redis as the io.sign backend.
- A PostgreSQL 17 or later database of its own. It can be on the same server as the io.sign database.
- The same identity provider settings as the io.sign backend, so it accepts the same tokens.
- Outbound HTTPS access to your subscribers' URLs.
Configure the service
The webhooks service reads its database settings from WEBHOOKS_DB_* variables. These work like the backend's Postgres variables, including WEBHOOKS_DB_READER_* for a read replica.
NODE_ENV=production
STAGE=prod
WEBHOOKS_API_PORT=3010
# Webhooks database
WEBHOOKS_DB_HOST=postgres.internal
WEBHOOKS_DB_PORT=5432
WEBHOOKS_DB_NAME=io_sign_webhooks
WEBHOOKS_DB_USER=io_sign_webhooks
WEBHOOKS_DB_PASSWORD=<secret>
WEBHOOKS_DB_SSL_ENABLED=true
# The same Redis as the io.sign backend
REDIS_HOST=redis.internal
REDIS_PORT=6379
# The same identity providers as the io.sign backend
JWT_ENABLED=true
JWT_PROVIDERS=<same-value-as-the-backend>
# Delivery signing
WEBHOOKS_SIGNING_ENABLED=true
WEBHOOKS_SIGNING_ROOT_KEY=<secret>| Variable | Default | Description |
|---|---|---|
WEBHOOKS_API_PORT | 3010 | Port for the /v1/webhooks API and health check. |
WEBHOOKS_BLOCK_PRIVATE_TARGETS | true | Refuses to deliver to private, loopback, link-local, cloud metadata, and reserved addresses, so a subscription can't be used to reach your internal network. |
WEBHOOKS_RESPONSE_SNIPPET_LIMIT | 2000 | Characters of a subscriber's response stored with each attempt. |
Retry settings are in Delivery retries. Signing settings are in Webhook signing configuration.
Leave
WEBHOOKS_BLOCK_PRIVATE_TARGETSon in production. Turn it off only in a test environment where subscribers run on a private network.
Deploy the service
-
Create an empty database and a user with DDL privileges for it.
-
Run the webhooks migrations image against the database:
docker run --rm --env-file ./webhooks.env <registry>/<webhooks-migrations-image>:<tag> -
Start the webhooks service:
docker run -d --name io-sign-webhooks --env-file ./webhooks.env \ -p 3010:3010 <registry>/<webhooks-image>:<tag> -
Route
/v1/webhooksand/v1/webhooks/*on your API hostname to the webhooks service, and every other path to the io.sign REST API. -
Check the service:
curl https://sign.example.com/v1/webhooks/health
Run two or more replicas for availability. Obtain the image names and a tag compatible with your io.sign release from io.finnet. On upgrade, run the webhooks migrations before you roll the service, as you do for the backend in Migrations and upgrades.
Updated 17 days ago