Organisations and Projects
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 contains 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 Organization on the dashboard:
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.
Adding new members
In the Community Edition, all users are superusers, so all users can invite other team members.
To add a new team member, visit the teams page at the top middle of the page.
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.
After you create the invite, you can copy the invite link.
A project is a hierarchical namespace for all core resources within Convoy. All events, applications, 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 projects are designed for use by API consumers, they act as proxy and store for all the webhook events received from numerous third parties like GitHub, Twilio, Stripe etc., and even custom sources which require a certain form of verification. They support a number of handy features like webhook event type filtering, payload filtering and payload transformations.
Outgoing projects are designed for use API providers, they are used to send wehbook events to a consumer endpoint. Events can be sent using the HTTP API or via message brokers which include Google PubSub, Amazon SQS and Apache Kafka after which Convoy will dispatch them to the respective endpoints.
Configure a Project
The following are parameters that can be configured on a project.
|Mechanism||String||Linear time retry, Exponential time backoff||Linear time retry|
|Disable Failing Endpoint||Boolean||False|
|Retention Policy||Duration String||720h (30 days)|
|Search Policy||Duration String||720h (30 days)|
|Enable Meta Events||Boolean||False|
Note: Setting the Project's Disable Failing Endpoint config to
False will automatically set all the endpoints for that project with an
pending state to an
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.
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.
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.