Convoy provides the tools to properly categorise your data. These tools are organisations and projects.


An organisation is the highest level namespace within a Convoy instance. It comprises several projects. Ideally, this should map to a real-world organisation or some form of high-level grouping.

As a new user, an organization can be created by clicking on the Create Organisation on the dashboard:

Create organization

To switch between organizations, open the current organization’s settings, or create a new organization, use the account dropdown on the right of the top bar.

Organization operations

Adding new members

In the Community Edition, all users are super users, so all users can invite other team members.

Before doing this, ensure you have your SMTP configuration set up.

Team page

To add a new team member, visit the teams page at the top middle of the page.

Add new teammate

Once the invite is sent, the user will get an email with an invitation link to join the new project. An invitation token is valid for 2 weeks after which you’d need to generate a new one.


A project is a hierarchical namespace for all core resources within Convoy. All events, endpoints, subscriptions and all other critical configurations belong to a project and a project belongs to an organisation.

There are two types of projects; Incoming and Outgoing projects.

Incoming and outgoing projects

Incoming project

An incoming project is designed to receive webhooks from third-party party sources like Github, Twilio, Stripe etc. and even custom sources based on any form of verification. It was designed for API consumers.

Outgoing project

An outgoing project is designed to publish webhooks to users’ endpoints. It is designed for API providers.

Configure a Project

Project configurations

The following are parameters that can be configured on a project.

ConfigTypeSupported ValuesDefault
Signature Details
Retry Logic
MechanismStringLinear time retry, Exponential time backoffLinear time retry
DurationDuration String5s
Rate Limit
DurationDuration String5s
Disable Failing EndpointBooleanFalse
Retention PolicyDuration String720h (30 days)
Search PolicyDuration String720h (30 days)
Enable Meta EventsBooleanFalse

Retention policies

Convoy uses retention policies to preserve webhook events sent from your Convoy application or received to your Convoy application. The default period for retaining webhook events is set to 30 days.

The retention policy can be configured during project initialisation or modified from the project settings for an existing project.

Retention policy

Relationship with subscription

All these configurations act as sensible defaults for all subscriptions in a project. A project can’t exist without all these parameters defined in the project. Each configuration can also be described on subscriptions in a project, where a subscription doesn’t define these parameters, we fall back to the project’s defaults.

Multiple Projects

There are several practical ways of using projects:

  • A project per environment: You can decide to test your integration with a development or staging environment, before going live to a production environment to keep data separate.
  • A project per product: If you have several projects, you can scope them differently on Convoy too.