Community

GitHub

Tutorials

Convoy

API Reference

Start Your Project

Overview

Find the guides, samples, and references you need to use Convoy to start sending out and receiving webhook events as fast as possible.

Quickstart

Convoy is an open-source high-performance webhooks gateway to manage millions of webhooks end-to-end.

Introduction

Send Webhook Events

Send Event

Send Your First Webhook Event

Receive Webhook Events

Receive Event

Receive Your First Webhook Event

Use Convoy as a Webhook Proxy to deliver webhooks with one API

Use Convoy as a Webhook Proxy

Use Convoy as a Proxy

We wrote this guide for webhook providers looking to add webhooks to their API or improve their webhooks delivery system. Here are a few best practices to keep in mind while generating webhook payloads

Best practices for generating webhook events

Convoy is made up several services working in tandem such as workers, Egress, Ingest, Schedulers, Server.

Convoy Architecture

Architecture

Convoy is made up several services working in tandem such as workes, Egress, Ingest, Schedulers, Server.

Convoy can be configured using CL Flags, Environment Variables or a configuration file.

Convoy Configuration

Configuration

Install Convoy with Docker

Docker

Install Convoy using Kubernetes

Kubernetes

Troubleshooting

Organizations and Projects

An endpoint is a valid HTTP URL that can receive webhook events.

Endpoints

Webhook signatures are strings used to verify the validity of a webhook event sent to Convoy.

Signatures

Sources are how events are ingested into Convoy. Convoy currently supports three types of sources - REST API, HTTP Ingested and Message Brokers such as Google PubSub, Amazon SQS and Kafka.

Sources

Subscriptions are conduits through which events are routed from a source to a destination (endpoint) in Convoy

Subscriptions

An event delivery is the combination of an endpoint and an event. For both incoming and outgoing webhooks project, an event can generate multiple event deliveries depending on the subscriptions.

Events and Event Deliveries

The portal link serves as a medium to quickly generate portals for users to review and debug events from a publisher

Portal Links

Meta events are operational events generated by Convoy for specific activities happening within your Convoy project.

Meta Events

Idempotent HTTP requests refer to the characteristic of certain HTTP methods that allows them to be safely and repeatedly executed without altering the state of the server beyond the initial request.

Idempotency

Static IP addresses are how we ensure all webhook events originate from the correct source without malicious entities impersonating the source.

Static IP addresses

Static IPs

Webhooks are a mechanism for notifying third-party applications about a change in their account in real time.

Webhooks

Webhooks Documentation

Convoy CLI

Convoy provides SDK for in-app integration. These SDKs carry out the same operations as the API and Convoy dashboard.

Convoy SDK Documentation

Releases

This section collects brief definitions of some of the technical terms used in the documentation for Convoy.

Glossary

Convoy tracks usage of its products which helps the team to improve and deliver better software. All telemetry data are collected and stored securely on Mixpanel.

Telemetry

We adopt a time-based release schedule; this means we release a new software update on the 25th of every month. Over the course of the month we break this cycle to ship security patches and severe bug fixes reported. We decided to adopt this pattern to constantly be shipping updates to our users. This is similar pattern adopted by open source companies like [Gitlab](https://about.gitlab.com/releases/) and [Sentry](https://develop.sentry.dev/self-hosted/releases/).

Release Process

Release Cycle

Welcome

Authentication

Errors

Pagination

Versioning

List all endpoints

Create an endpoint

Retrieve endpoint

Update an endpoint

Delete endpoint

This endpoint expires and re-generates the endpoint secret.

Roll endpoint secret

This endpoint toggles an endpoint status between the active and paused states

Pause endpoint

This endpoint retrieves all event deliveries paginated.

List all event deliveries

This endpoint batch retries multiple event deliveries at once.

Batch retry event delivery

This endpoint enables you retry a previously successful event delivery

Force retry event delivery

Retrieve an event delivery

Retry event delivery

This endpoint fetches an app message's delivery attempts

List delivery attempts

This endpoint fetches an app event delivery attempt

Retrieve a delivery attempt

This endpoint fetches app events with pagination

List all events

Create an event

This endpoint creates a event that is broadcast to every endpoint whose subscription matches the given event type.

Create a broadcast event

This endpoint replays multiple events at once.

Batch replay events

This endpoint does not require creating endpoint and subscriptions ahead of time. Instead, you supply the endpoint and the payload, and Convoy delivers the events

Dynamic Events

This endpoint uses the owner_id to fan out an event to multiple endpoints.

Fan out an event

Retrieve an event

This endpoint replays an event afresh assuming it is a new event.

Replay event

This endpoint fetches meta events with pagination

List all meta events

Retrieve a meta event

Retry meta event

This endpoint fetches multiple portal links

List all portal links

Create a portal link

This endpoint retrieves a portal link by its id.

Retrieve a portal link

Update a portal link

Revoke a portal link

List all sources

Create a source

This endpoint retrieves a source by its id

Retrieve a source

Update a source

Delete a source

This endpoint fetches all the subscriptions

List all subscriptions

Create a subscription

This endpoint validates that a filter will match a certain payload structure.

Validate subscription filter

This endpoint test runs a transform function against a payload.

Test a subscription function

This endpoint retrieves a single subscription

Features	Incoming	Outgoing
Purpose	For API consumers. In this scenario, Convoy acts as a reliable ingress for webhook events.	For API providers. In this scenario, Convoy acts as a reliable egress for webhook events.
Portal	You don’t need a portal because you have access to the entire dashboard.	Each API consumer needs a portal to view their specific endpoint webhook logs.
Event Sources	Events are ingested only through HTTP source URLs.	Events are ingested through REST API and PubSub systems like Amazon SQS, Google PubSub, etc.

Name	Location	Precedence	Rationale for overriding
`api_version`	convoy.json	0
`CONVOY_API_VERSION`	environment variables	1	Environment variables take precedence over values set in convoy.json
`X-Convoy-Version`	http headers	2	Each http request can pin the version if they want to fetch content in a particular format

Home

Guides

Deployment

Product Manual

Command Line

SDK

Release Notes

Resources

FAQ

FAQ

What is the difference between an incoming and an outgoing webhooks project?

How does API versioning work?

Server API Version

Client API Version

API Version Precedence