HTTP codes

Sample Error Response

Community

GitHub

Status

Convoy

API Reference

Webhook Guides

Changelog

Start Your Project

Errors

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 consists of several services working in tandem such as the Server and the Agent.

Convoy Architecture

Architecture

Convoy can be configured using CLI 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

Apache Kafka

Amazon SQS

Google PubSub

RabbitMQ

Rate Limits

Filtering is used to decide what events an endpoint will receive based on the webhook event payload.

Filters

Functions are used to mutate webhook payloads (event data)

Functions

Convoy exports metrics about the state of events received and sent via Prometheus.

Metrics

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

Overview

This section describes how changes to Convoy Cloud are managed for Minor Upgrades, Major Upgrades and Deprecations for Convoy Cloud

Cloud Upgrade Policy

Convoy Cloud Upgrade Policy

At Convoy Cloud, we ensure a seamless subscription experience with a flexible grace period for payment issues.

Convoy Cloud Subscription and Access Policy

Upgrading Convoy with a license key

Licensing

Paid Features

Enterprise SSO

Single sign-on

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

Convoy adopts an incremental approach with feature flags to release new features.

Feature Flags

Convoy Support Policy for Self-Hosted Customers

Support Policy

Webhook Retries

This article explores strategies to combat SSRF attacks in webhook systems, focusing on IP Validation & Filtering and Egress Proxy implementation in Convoy.

Webhook Security: Tackling SSRF

Core Gateway

Welcome

Authentication

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

Toggles an endpoint's status between 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

Create an event type

Updates an event type

This endpoint fetches the project's event types

Retrieves a project's event types

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

Code	Description
`201 Created`	Resource was created successfully
`400 Bad Request`	The request failed due to an unacceptable, most commonly an invalid parameter.
`401 Unauthorized`	A request to a protected endpoint did not have a valid API Key.
`404 Not Found`	Resource does not exist.

Introduction

Endpoints

Event Deliveries

Event Types

Delivery Attempts

Events

Meta Events

Portal Links

Sources

Subscriptions

Errors

HTTP codes

Sample Error Response

Introduction

Endpoints

Event Deliveries

Event Types

Delivery Attempts

Events

Meta Events

Portal Links

Sources

Subscriptions

​HTTP codes

​Sample Error Response

HTTP codes

Sample Error Response