DOCSEARCHbyAlgolia
Submit Docs

Convoy API Reference

website·Indexed 34 days ago

https://getconvoy.io/docs

RESTful API documentation for Convoy, covering event delivery, endpoint management, and event type configuration. Includes endpoints for creating and replaying events, managing subscription filters, handling OAuth2 connections, and tracking delivery attempts using Bearer token authentication.

Tokens
54.5K
Snippets
277
Records
429
Agent score
67%

What's inside Convoy

  1. Overview of Convoy Webhooks Gateway

    Convoy is an open-source, high-performance, multi-tenant webhooks gateway designed to manage millions of webhooks end-to-end. It supports both sending and receiving webhooks and includes built-in features for reliability and management, such as retries, rate limiting, circuit breaking, and customer-facing webhooks dashboards.

  3. Overview of Convoy Meta Events

    Meta events are operational events generated by Convoy for specific activities happening within a Convoy project. These events are delivered via webhooks, allowing developers to subscribe to them and trigger actions within their own internal systems for a headless experience.

  4. Circuit Breaker technical implementation details

    The Circuit Breaker uses the following technical architecture:

    • Storage: State (Closed/Open/Half-Open, request counts, failure counters, reset timestamps, and notification history) is stored in Redis with expiration matching the observability window.
    • Metrics: Health is determined by querying actual delivery success and failure counts from the database, grouped by endpoint and project within the observability window.
    • High Availability: Distributed locking ensures only one Convoy agent instance samples at a time. The lock TTL matches the sample rate, and the system fails-open if a sampler crashes.

  5. Understand Convoy Webhook Signature types

    Convoy uses the X-Convoy-Signature header to allow receivers to verify that a webhook event was sent by Convoy. There are two types of signatures:

    1. Simple Signatures: A single hash string used for basic validation.
    2. Advanced Signatures: Include a timestamp (t) and one or more signature hashes (v0, v1, etc.). This format helps prevent replay attacks by allowing the receiver to verify the event's age.
    // Simple Signature Example
X-Convoy-Signature: 6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39

// Advanced Signature Example
X-Convoy-Signature: t=1492774577,v1=ansdoj...,v0=6ffbb...

  6. Manage Convoy Control Plane and Data Plane with Core Commands

    Convoy uses a split architecture between the control plane (server) and data plane (agent). Both typically share the same convoy.json configuration or environment variables.
    # Start the Control Plane (Dashboard and Management API)
convoy server --port <port>

# Start the Data Plane (Queue consumers, broker ingest, metrics)
convoy agent --port <port>

# Print the resolved configuration as JSON
convoy config --config <path_to_config>

# Apply pending database migrations
convoy migrate up

  7. Deploy a self-hosted 3-node Redis Sentinel architecture

    For high availability, a 3-node architecture is recommended to ensure a quorum (majority vote) for automatic failover. If only 2 nodes are used, losing one prevents quorum and automatic failover.

    VM Specifications per Node:

    • vCPU: 2-4 (Redis is single-threaded for commands, but needs extra for persistence/replication).
    • RAM: 8 GB (Set maxmemory to ~75% of RAM, e.g., 6 GB).
    • Disk: 20 GB SSD (Required for RDB snapshots and AOF files; SSD is critical to avoid latency spikes).

    Scaling Note: For workloads above ~10M requests/day, increase RAM to 16 GB per node.

  8. Ingest events via Message Brokers

    Message Brokers allow backend services to write events to a queue or topic, which Convoy then reads and dispatches to client endpoints. This is available for outgoing projects. Supported brokers include:

    • Apache Kafka
    • Amazon SQS
    • Google PubSub
    • RabbitMQ (Beta)

  9. Configure custom CA certificates for TLS verification

    Convoy supports custom Certificate Authority (CA) certificates to enable secure connections to endpoints signed by private or internal CAs. Custom CA certificates are loaded alongside system CA certificates. This feature is available only for licensed users with Custom Certificate Authority access enabled. The configuration applies to the Server, Agent, and Worker components.

  10. Convoy Architecture Overview

    Convoy uses a distributed architecture consisting of a stateless API Server, stateless Agents, and an Egress proxy. Events sent via the API are enqueued to a task queue (Redis by default, or optionally PostgreSQL) where Agents process and persist them before dispatching to endpoints via the Egress service.

  11. Understand Circuit Breaker state transitions

    The circuit breaker manages endpoint health using three states:

    1. Closed (Normal): All requests flow normally. Transitions to Open when the failure rate exceeds the failure_threshold and minimum_request_count is met.
    2. Open (Tripped): Requests are blocked. Transitions to Half-Open automatically after the error_timeout expires.
    3. Half-Open (Recovery): Limited requests are allowed. Transitions back to Closed if the success_threshold is met, or returns to Open if failures continue.

    Automatic Disabling: If an endpoint trips the circuit breaker repeatedly, it will be automatically disabled after reaching the consecutive_failure_threshold.

  12. Understand and use Projects for environment and team isolation

    Projects in Convoy serve as logical contexts used to isolate different environments (such as development, staging, and production) or separate teams within a single Convoy deployment. This allows each project to maintain its own distinct login details and operational context while sharing the same underlying deployment.