Skip to main content
Convoy is operated through the HTTP API and dashboard. There is no single “import tenant” endpoint that creates an entire organisation graph in one request. For large or repeatable setups, use a script or infrastructure-as-code that calls the API in a defined order, driven by the OpenAPI specification.

​
Suggested provisioning order

  1. Organisation: Create or select the organisation that owns the work.
  2. Project: Create an incoming or outgoing project (see Organisations and projects).
  3. Sources (incoming): Define how events enter Convoy (HTTP, REST API, broker-backed, etc.); see Sources.
  4. Endpoints (outgoing): Define destination URLs, timeouts, auth, and optional verification considerations. For many endpoints at once inside an existing project, use bulk onboard after the project exists (and configure sources separately if your topology needs explicit source links).
  5. Subscriptions: Link sources to endpoints (filters, retry policy, functions); see Subscriptions.
Re-run or update the same resources idempotently where the API allows; for event ingestion deduplication, see Idempotency.

​
Bulk onboard

POST /api/v1/projects/{projectID}/onboard creates endpoints and matching subscriptions in bulk inside a project you already have. It does not replace the full provisioning order above; use it after your project exists.

​
Payload formats

Send either JSON or a CSV file (not both in the same request). JSON (Content-Type: application/json): 
{
  "items": [
    { "name": "Acme Production", "url": "https://acme.example.com/webhooks", "event_type": "invoice.paid" },
    { "name": "Acme Staging", "url": "https://staging.acme.example.com/hooks", "auth_username": "convoy", "auth_password": "s3cret" }
  ]
}
Each item requires name and url. Optional fields: event_type (defaults to *, all events), auth_username and auth_password (must both be set or both omitted). CSV (Content-Type: multipart/form-data, field name file, max 10 MB): 
name,url,event_type
Acme Production,https://acme.example.com/webhooks,invoice.paid
Acme Staging,https://staging.acme.example.com/hooks,
Required columns: name, url. Optional columns: event_type, auth_username, auth_password.
1

Dry run

Add ?dry_run=true to validate your payload without creating anything:
curl -X POST "https://dashboard.getconvoy.io/api/v1/projects/{projectID}/onboard?dry_run=true" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"name": "Test", "url": "https://example.com/hook"}]}'
A 200 response returns validation results:
{
  "status": true,
  "message": "Dry run validation complete",
  "data": {
    "total_rows": 1,
    "valid_count": 1,
    "errors": []
  }
}
If there are problems, errors lists each one with row, field, and message.
2

Fix validation errors

Correct any rows flagged in the dry-run response and re-run until errors is empty.
3

Submit

Remove the dry_run parameter and POST the same payload. A 202 confirms the request is accepted:
{
  "status": true,
  "message": "Bulk onboard request accepted",
  "data": {
    "batch_count": 1,
    "total_items": 2,
    "message": "Bulk onboard request accepted for processing"
  }
}
Work is processed asynchronously in batches of up to 50 items. If you submit without dry_run and there are validation errors, the API returns 400 with the same error shape as the dry run.
4

Verify

Poll the list endpoints and list subscriptions APIs, or check the dashboard, until the expected resources appear.
For CSV uploads, use -F instead of -d: 
curl -X POST "https://dashboard.getconvoy.io/api/v1/projects/{projectID}/onboard" \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]"

​
Limits

LimitValue
Maximum items per request1,000
Batch size (items per queue job)50
Multipart form size (CSV upload)10 MB

​
What gets created

For each valid row the processor creates:
  • Endpoint: active status, application/json content type, auto-generated signing secret.
  • Subscription: named {name}-subscription, type api, event type filter set from event_type (default *). No source is attached; if you need source-to-endpoint wiring for incoming projects, update the subscription via the subscriptions API after onboard.
If auth_username and auth_password are both provided, the endpoint is configured with HTTP Basic outbound auth. Basic auth requires an enterprise license and the organisation early adopter flag. See Endpoint authentication for details.

​
Self-hosted note

The Convoy agent (convoy agent) must be running to process onboard batches. If it is not, jobs sit in the queue and endpoints will not appear until the agent starts.

​
Export, audit, and backups

  • API listing: Use list endpoints (projects, endpoints, subscriptions, etc.) to snapshot configuration for audits or drift detection.
  • Self-hosted: Database backups and restores are your operational responsibility; Convoy stores configuration and state in PostgreSQL.
  • Hosted / Cloud: Follow your provider’s export and support processes for tenant data.
For load and capacity validation after onboarding, see Architecture, specifically the Benchmarks & Performance section, component sizing, and scaling notes.