Convoy: An Open-Source Webhooks Gateway with Fan-out, Retries, and Circuit Breaking

The Webhooks Reliability Problem Convoy Addresses

Sending webhooks directly from an application server means the application must handle retries when the endpoint is down, track which deliveries succeeded, manage rate limits for each customer, and build a dashboard for customers to debug failed events. Convoy moves all of that work to a dedicated gateway.

The README describes Convoy as an open-source high-performance webhooks gateway for securely ingesting, persisting, debugging, delivering, and managing millions of events. As a gateway, it sits at the edge of the network. Outgoing webhooks from internal microservices flow through Convoy to customer endpoints without exposing internal services directly. Incoming webhooks from third-party providers flow through Convoy to internal services. The result is a single observability and control plane for all webhook traffic.

Delivery Architecture: Server, Agent, and the Queue

Convoy is split into two independently scalable components: `server` and `agent`. The server handles ingest, the API, and the dashboard. The agent handles delivery. Because they scale independently, a team with high ingest volume but modest delivery requirements can scale the server without scaling the agent, and vice versa.

The delivery queue defaults to Redis, which is the standard production configuration. An experimental Postgres-based queue is also available; the README notes this requires a license key to enable. The go.mod file lists `github.com/hibiken/asynq` as the queue implementation for Redis and `github.com/jackc/pglogrepl` for the Postgres replication-based queue. Event persistence uses Postgres as the primary database, with `github.com/jackc/pgx/v5` as the driver. Static IP support is listed as a feature, which is relevant for customer endpoint environments with strict firewall rules.

Deploying Convoy with Docker or Kubernetes

The README lists two deployment paths: Docker and Kubernetes with Helm. The Docker path links to the installation documentation at docs.getconvoy.io/deployment/install-convoy/docker. The Kubernetes path uses a Helm chart at docs.getconvoy.io/deployment/install-convoy/kubernetes. Both paths require an external Postgres and Redis instance, which are not bundled with the main Convoy container image.

The repository includes a `docker-compose.dep.yml` file for dependency services (Postgres and Redis), a `docker-compose.dev.yml` for local development, and a `docker-compose.sentinel.yml` for Redis Sentinel configuration. A `convoy.env.example` and `convoy.json.example` at the repository root provide configuration templates. The monitoring directory and `.env.example` file show integration with Loki for log aggregation and Prometheus for metrics, using the `LOKI_URL` and `CONVOY_INSTANCE_NAME` environment variables.

Fan-out, Filters, Transforms, and Dynamic Endpoints

A single event can be delivered to multiple endpoints through fan-out routing, which the README describes as routing based on event type or payload structure. Subscriptions can filter incoming events on body, headers, query parameters, and path before delivery. A JavaScript transform can run before delivery to reshape the payload. Events that do not match a subscription's filter are dropped rather than queued.

Dynamic endpoints allow registering a URL template rather than a fixed endpoint URL. Convoy fills in the destination URL per event at delivery time. The README describes a `POST /events/dynamic` endpoint that can wait until the event is matched before returning a 201 status. This pattern is useful for multi-tenant applications where each tenant has a unique endpoint URL derived from their account identifier. The circuit breaker opens when an endpoint fails consecutively, and Convoy probes the endpoint before resuming normal traffic.

Licensing: Elastic License v2.0 and What It Restricts

Convoy's license is the Elastic License v2.0, listed in the repository as `NOASSERTION` in the metadata but identified clearly as ELv2 in the README. The ELv2 allows free use, modification, and self-hosting. The restriction it adds is on competitive use: you may not offer Convoy itself as a hosted service to third parties. A company building its own product that uses Convoy internally is permitted; a company running a managed Convoy hosting service is not.

The community self-hosted tier is free for one user, one organization, and two projects. Additional features, including the experimental Postgres queue and other enterprise capabilities, require a license key. The README describes adding a license key to a self-hosted instance to enable paid features, which means the codebase is shared between the community and enterprise editions with feature gating rather than separate code branches. Svix is a direct alternative that operates as a hosted service; the key difference is that Svix is a managed SaaS product while Convoy is self-hosted.

Maintenance and SDK Coverage

The last push to the Convoy repository was on 2026-09-24, and release v26.8.0 was published on 2026-09-28. The versioning scheme uses a year-and-month format (v26.8.0 for 2026 August), indicating the project follows a calendar-based release schedule. The repository is not archived.

Convoy ships official client SDKs in Go, Python, JavaScript, Ruby, PHP, and Java, generated from the OpenAPI specification. The README notes that signature verification is hand-written and shared across languages rather than generated, which matters for security-critical integrations. Team management features include organization invites with role assignment and Google SSO support when enabled on the instance. The project uses the Slack community and a forum at community.getconvoy.io for support questions.

Editorial conclusion

Convoy suits engineering teams that send webhooks to multiple customers and need retries, filtering, fan-out, and a debugging dashboard without building all of that from scratch. The self-hosted community tier is free for one user, one organization, and two projects; teams that need more should check the license terms before deploying. The Elastic License v2.0 restricts offering Convoy as a managed service. The last push was on 2026-09-24, and the v26.8.0 release was published on 2026-09-28.

Frequently asked questions

Official sources

1. frain-dev/convoy on GitHub
2. Issues
3. Project website
4. README
5. Releases