charon

module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 22, 2026 License: Apache-2.0

README

Charon

An inbound webhook gateway. It accepts webhooks, stores them before acknowledging, then routes and delivers them with retry, dead lettering, search and replay.

Single binary, one PostgreSQL database, no other runtime dependencies.

Status

First release. Charon accepts a webhook, checks its signature, records it durably, acknowledges it only after that record is committed, then delivers it to the destinations routed for its provider — signed on the way out — retrying with backoff until the destination answers 2xx or the attempt limit is reached. Every event and every attempt is searchable and replayable from the panel, per tenant, by operators who sign in with your own identity provider.

Young, and versioned accordingly: 0.x means the shape of things can still change between minor versions, and anything that does will say so in the release notes.

Requirements

  • Docker, to run the stack and the tests
  • PostgreSQL 18 if you run it yourself; Go 1.27 or newer to build from source

Quick start

git clone https://github.com/edersonangelo/charon.git
cd charon
docker compose up -d

That is the whole thing: PostgreSQL, the schema, and Charon listening on :8080. Then send it something:

curl -i -X POST localhost:8080/webhooks/stripe \
  -H 'Content-Type: application/json' \
  -d '{"id":"evt_1","type":"charge.succeeded"}'
HTTP/1.1 202 Accepted
Content-Type: application/json

{"id":"01a06d07-dbe6-76fc-b20d-cb1a70e16c12"}

202 means the request is committed to the database, not that anything has been done with it. The identifier is how the event is found again.

Malformed bodies, unknown providers and unmapped event types are accepted and recorded too. The inbound port does not read the payload, so nothing about its content can cause a rejection.

Create an operator and open the panel at http://localhost:8080:

docker compose run --rm charon user add -email you@example.com

That operator owns the default tenant, which is the only one until you add another.

A Postman collection covers every route and asserts its own status codes, so a green run is a working gateway.

PostgreSQL is published on 5434 and Charon on 8080. Override with POSTGRES_HOST_PORT and CHARON_HOST_PORT if either is taken.

Running from source

docker compose up -d postgres
make build

export CHARON_DATABASE_URL='postgres://charon:charon@localhost:5434/charon?sslmode=disable'
./bin/charon serve

Or without cloning anything:

go install github.com/edersonangelo/charon/cmd/charon@latest

Binaries for linux and macOS, on both architectures, are attached to every release.

Install

docker pull edersomangelo/charon:latest

linux/amd64 and linux/arm64, built from scratch, running as uid 65534. PostgreSQL 18 is yours to provide.

Running it standalone or under Kubernetes, and what each tag promises, are in docs/install.md.

Commands

charon serve      Accept inbound webhooks and record them
charon dispatch   Deliver recorded events to their destinations
charon route      Manage where a provider's events are delivered
charon user       Create an operator who can sign in to the panel
charon verify     Configure how a provider's signature is checked
charon tenant     Manage the tenants events are recorded for
charon role       Manage roles, what they grant and who gets them
charon migrate    Apply pending schema migrations and exit
charon version    Print the build version

Every flag, with the reason it exists, is in docs/command-line.md.

Verification

A provider's signature is checked from stored parameters, not from code written for that provider. Presets cover the common ones:

echo "CHARON_SECRET_STRIPE=whsec_..." >> .env
docker compose up -d
docker compose run --rm charon verify set -provider stripe \
  -preset stripe -secret-env CHARON_SECRET_STRIPE
docker compose run --rm charon verify presets
docker compose run --rm charon verify list

The database holds the name of the environment variable, never the secret, which is why the secret goes in .env — the shell's environment is not the container's, and the process that checks signatures has to be the one that can read it. A provider that no preset fits is configured by its parameters instead — -verifier, -scheme, -algorithm, -encoding, -header — which is the same mechanism the presets are made of.

A signature that fails does not reject the request: the outcome is recorded on the event and shown in the panel, and a request that failed is kept so it can be looked at. Nothing that failed is delivered. Once the secret is right, charon verify recheck -provider stripe checks the refused requests again and reopens the ones that now pass.

Some providers will not accept a callback address until the address answers for itself. WhatsApp, Instagram and Messenger send a GET carrying a token you chose and a value to echo back, and deliver nothing until they get that value:

printf 'CHARON_SECRET_WHATSAPP=%s\nCHARON_VERIFY_WHATSAPP=%s\n' \
  'the-app-secret' 'a-token-you-chose' >> .env
docker compose up -d --force-recreate charon
docker compose run --rm charon verify set -provider whatsapp-bussines \
  -preset whatsapp-bussines -secret-env CHARON_SECRET_WHATSAPP \
  -verify-token-env CHARON_VERIFY_WHATSAPP

Then the callback address is https://your-host/webhooks/whatsapp-bussines, and the verify token is the one you put in CHARON_VERIFY_WHATSAPP. Charon answers 200 with the value the provider asked it to echo, 403 to anyone offering a different token, and 405 for every provider with no handshake configured. A variable that is named but not set in the serving process answers 503, because the value gets there by a deploy rather than by anything that process can do, so the provider is told to come back — and charon verify list names that case.

Like the secret, the database holds only the name of the variable. The two are independent: a provider can have a signature, a handshake, both, or neither.

Re-running verify set without naming the variable keeps the one already stored, so rotating a secret never switches a handshake off by omission. -clear-verify-token is how one is switched off, and it says so.

Tenants

Everything recorded belongs to a tenant: events, routes, destinations, verification settings and operators. A deployment that never asks for a second one works as if the concept did not exist — default is created by the migration and every command acts for it.

docker compose run --rm charon tenant add -slug acme -name 'Acme Inc'
docker compose run --rm charon tenant list

The panel has a tenants page for the same thing, for an operator whose role grants tenants.write. An operator belongs to one tenant; a system administrator belongs to none and moves between them, which is the only way to reach more than one. The first one is made with charon user superadmin -email you@example.com, and only somebody who already is one can make another.

The address a webhook arrives at decides the tenant:

POST /webhooks/{provider}            the default tenant
POST /webhooks/{tenant}/{provider}   that tenant
GET  /webhooks/{provider}            the handshake, for a provider that asks for one
GET  /webhooks/{tenant}/{provider}   the same, for that tenant

An address naming a tenant that does not exist is refused with 404, a handshake offering the wrong token with 403, and one whose token cannot be read in the serving process with 503. Those are the only rejections Charon makes that are not about a resource limit, and all three are about a handshake or an address: a delivery is never refused for anything its body says. Every other command takes -tenant, which defaults to default and to CHARON_TENANT.

Keeping tenants apart is Charon's job: every row carries the tenant it belongs to, and every query is scoped to one. Nothing else is required of the deployment — one database, one role, and creating a tenant is creating a tenant.

The same rule exists one layer down for a deployment that wants it. Every tenant scoped table has row level security forced on it, and the tenant a connection acts for is set on the connection, so the database refuses another tenant's rows whatever a query asks for. PostgreSQL exempts superusers and roles carrying BYPASSRLS, so that layer applies only when charon serve connects as a role with neither:

create role charon_app login password '<choose one>' nosuperuser nobypassrls;
grant usage on schema public to charon_app;
grant select, insert, update, delete on all tables in schema public to charon_app;
grant execute on all functions in schema public to charon_app;

It is worth having and it is not a prerequisite. charon dispatch acts for no tenant — it delivers rows that each carry their own — so it stays on a role that is not confined.

Routing

Nothing is delivered until a provider has a route. Adding one takes no deploy and no restart:

docker compose run --rm charon route add -provider stripe -url https://api.internal/webhooks/stripe
docker compose run --rm charon route list

An event recorded for a provider with no enabled route waits. It is not discarded and it is not marked as handled: the moment a route appears, the next dispatch round delivers it. Configuring the route after the first event arrives costs nothing.

Delivery

charon dispatch claims due deliveries under a lease, posts the raw body to the destination, and closes the delivery only when the destination answers 2xx. Anything else counts an attempt and schedules a retry with exponential backoff and jitter. At the attempt limit the delivery becomes dead, which is never counted as delivered.

Each request carries X-Charon-Delivery-Id, X-Charon-Event-Id, X-Charon-Provider and X-Charon-Attempt, plus the original Content-Type.

It does not poll on a fixed interval. An inbound record announces itself on commit, so a new event is picked up immediately, and between rounds the dispatcher sleeps until the earliest retry is actually due. The safety interval bounds that sleep, because a delivery can become due through a route that announced nothing — a replay, a manual change, an expired lease.

Flag Default Purpose
-workers 8 Deliveries attempted at once
-batch-size 50 Deliveries claimed per round
-safety-interval 30s Longest sleep before scanning anyway
-request-timeout 15s How long a destination has to answer
-max-attempts 12 Attempts before dead lettering
-backoff-base 5s First retry window
-backoff-cap 1h Largest retry window

Operator panel

The panel is served by the same binary, on the same port, with no separate build step and no external assets. Sign in with an operator created by charon user add.

  • Search by provider, delivery state, time window, event identifier, or any text inside the recorded body.
  • Inspect an event by clicking anywhere on its row, which opens the detail in a dialog: its headers and raw body exactly as received, every delivery it produced, and the full attempt history of each one — when it was tried, what the destination answered, how long it took, and why it failed. Each row also links to the same detail as its own page.
  • Configure everything from one place. The panel has two entries: events, which is the operation, and settings, which is routes, verification, operators, roles and tenants. Every control obeys the role of whoever is looking, on the page and at the route behind it: a control an operator may not use is not drawn, and the route behind it refuses anyway.
  • Replay a single delivery or every delivery of an event. A replay resets the delivery to pending and announces it, so it is picked up immediately. It does not erase the attempt history, and it unplans the event so a route added since is included.

Replaying is a real redelivery, not a simulation. The destination will receive the event again, which is the same situation described below.

Roles

What an operator may do is a role, and a role is a set of permissions. The permissions are fixed, because each one names something the code checks; the roles are not, because which of them a deployment wants is its own business. Four are shipped. They belong to no tenant and can be held in any, and a tenant may define roles of its own alongside them:

Role Grants
viewer read events, routes, verification and operators
operator everything a viewer can, and replay events
admin everything an operator can, and configure the tenant
owner everything an admin can, and manage tenants

Somebody belongs to a tenant as a role, and can belong to several holding a different one in each — a viewer here, an owner there. They see one tenant at a time, chosen in the panel's header. Belonging without a role stated is belonging as a viewer, which is the least there is.

All of it is done from the panel, on the operators page, and the command line mirrors it:

docker compose run --rm charon role permissions
docker compose run --rm charon role list
docker compose run --rm charon role set -name resender \
  -description 'sends events again' -grant events.read,events.replay

A permission nothing enforces cannot be granted. The set is closed in the code, because each permission names something a route checks, and it is a table in the database, so a grant points at a row: naming one that does not exist fails on a foreign key, not only on a check that could be skipped. The panel obeys the role on both sides — a control an operator may not use is not drawn, and the route behind it refuses anyway.

Somebody arriving from single sign-on holds the role the provider names — /acme/operator — or the least when it names only the tenant, and the panel decides from there. See Single sign-on.

Single sign-on

The panel accepts any OpenID Connect provider, discovered from its issuer url. Local accounts keep working alongside it, and nothing about single sign-on is gated: no licence key, no seat count, no call to any service this project controls.

CHARON_OIDC_ISSUER=https://sso.example.com/realms/main
CHARON_OIDC_CLIENT_ID=charon
CHARON_OIDC_CLIENT_SECRET=...
CHARON_OIDC_REDIRECT_URL=https://charon.example.com/auth/oidc/callback

The flow is authorization code with PKCE. The identity token is verified against the provider's keys and the nonce is checked against the one issued.

Where somebody lands is read from the values the provider sends — its groups, its roles, whatever it calls them. A value is a path: /acme/operator puts them in the tenant acme as an operator, /acme puts them there at the least, and a value naming no tenant is pointed at one from the panel. The token is what says where somebody belongs, so it is settled at every sign-in: a value that stops arriving takes the tenant with it.

Every provider needs one switch turned on for any of that to arrive, because OpenID Connect standardises identity and not authorisation. docs/single-sign-on.md is that switch, per provider, with a worked Keycloak example and what the log says when it is missing.

Delivery is at-least-once

Charon guarantees a recorded event reaches its destination. It does not guarantee it reaches it exactly once, and it cannot.

A destination can accept a delivery and have the acknowledgement lost on the way back: a dropped connection, a timeout on Charon's side, a restart between the 2xx and the write that records it. None of those look any different from a destination that received nothing, so Charon retries, and the handler sees the same event again.

Duplicates also arrive without Charon's help. Providers retry on their own, and two providers can report the same fact through independent paths.

Consumers have to be idempotent. The question to answer is not "have I seen these bytes before" but "have I already applied this effect", against your own state and keyed by the provider's event identifier. Recording a status can be repeated safely; charging a card cannot, and only the consumer knows which one it is doing.

Configuration

Flag Environment Default Purpose
-database-url CHARON_DATABASE_URL — PostgreSQL connection string. Required
-addr CHARON_ADDR :8080 Address to listen on
-log-level CHARON_LOG_LEVEL info debug, info, warn or error
-max-body-bytes — 1048576 Largest request body that will be recorded
-migrate — true Apply pending migrations before serving
-session-ttl — 12h How long a panel session lasts
-secure-cookie — off Mark the session cookie secure, for serving over HTTPS
-verification-refresh — 1m How often verification settings are reloaded regardless of announcements
-metrics-addr CHARON_METRICS_ADDR — Address to serve Prometheus metrics on, off when empty
-tenant CHARON_TENANT default Tenant the command acts for, on every command but serve and dispatch

GET /healthz reports that the process is up. GET /readyz reports whether the database is reachable, which is the only thing that makes an instance worth sending traffic to.

Metrics are served in the Prometheus format on a listener of their own, off until -metrics-addr names one — what a scrape reports is every tenant's counts, which does not belong on the port the internet posts webhooks to. See docs/metrics.md.

Events are kept for ever until a tenant says otherwise. charon retention set -tenant acme -days 90 says otherwise, and charon dispatch discards what is past it every hour — never an event whose delivery is still pending.

Documentation

  • docs/install.md — the published image, its tags, and running it standalone or under Kubernetes
  • docs/command-line.md — every command and flag, and why each one is there
  • docs/single-sign-on.md — connecting an identity provider, and how it decides who lands where
  • docs/signing.md — proving a delivery came from Charon, and verifying it on the receiving side
  • docs/metrics.md — what a scrape reports, and which number says the gateway is in trouble
  • CONTRIBUTING.md — development setup, branching, commits

Authorship

Some of the code in this repository was written with AI assistance.

The decisions were not. The architecture, the trade-offs and every change that landed here were reviewed and decided by me, including the places where I rejected what was proposed.

License

Apache-2.0

Directories

Path Synopsis
cmd
charon command
internal
auth
Package auth decides who an operator is.
Package auth decides who an operator is.
authz
Package authz decides what an operator may do, once auth has decided who they are.
Package authz decides what an operator may do, once auth has decided who they are.
handshake
Package handshake answers the GET some providers send before they will accept a callback address.
Package handshake answers the GET some providers send before they will accept a callback address.
ingest
Package ingest accepts inbound webhooks.
Package ingest accepts inbound webhooks.
provider
Package provider decides whether an inbound request really came from the provider it claims to be.
Package provider decides whether an inbound request really came from the provider it claims to be.
web
templ: version: v0.3.1020
templ: version: v0.3.1020

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL