DOCSEARCHbyAlgolia
Submit Docs

Convoy Webhooks Gateway

repository·main·Indexed 25 days ago

https://github.com/frain-dev/convoy

A high-performance, open-source webhooks gateway for securely ingesting, managing, and delivering millions of events. Convoy provides a dedicated message queue for webhooks with features including rate limiting, retries with exponential backoff, payload signing, fan-out routing, and embeddable customer dashboards for debugging and subscription management. It is designed for horizontal scalability with independent scaling of its api server, workers, scheduler, and socket server components.

Tokens
14.8K
Snippets
44
Records
120
Agent score
81%

What's inside Convoy

  1. Overview of Convoy Public API Clients

    main

    Convoy provides public API clients for the /api/v1 surface, generated from the OpenAPI specification located at docs/v3/openapi3.yaml. The clients are distributed across several language-specific repositories, each using a different generator to ensure idiomatic code:

    • JavaScript (convoy.js): Uses Speakeasy (Free tier).
    • Python (convoy-python): Uses openapi-python-client (OSS).
    • Java (convoy-java): Uses OpenAPI Generator (OSS) with java/native library (uses java.net.http + Jackson).
    • Go (convoy-go): Uses oapi-codegen (OSS) providing a client/ subpackage.
    • Ruby (convoy.rb): Uses OpenAPI Generator (OSS) providing a ConvoyApi namespace.
    • PHP (convoy-php): Uses OpenAPI Generator (OSS) providing a Convoy\Client namespace under src/Client/.

    Note on Webhooks: While API clients are generated, webhook signature verification is hand-written in every language using signature-vectors.json.

  2. Overview of Convoy Webhooks Gateway

    main

    Convoy is an open source, high-performance webhooks gateway designed to securely ingest, persist, debug, deliver, and manage millions of events. It acts as a dedicated message queue for webhooks and is designed to be horizontally scalable by allowing independent scaling of its api server, workers, scheduler, and socket server components.

    Key capabilities include:

    • Webhooks Gateway: Streams webhooks from microservices to users and routes incoming webhooks from providers to internal services, keeping internal systems off the public internet.
    • Security: Supports payload signing, bearer token authentication, and static IPs for strict firewall environments.
    • Fan Out: Routes events to multiple endpoints based on event type or payload structure.
    • Rate Limiting: Throttles event delivery to endpoints at configurable rates.
    • Retries: Supports constant time and exponential backoff with jitter, plus batch retries for consecutively failed endpoints.
    • Customer-Facing Dashboards: Provides embeddable iframes for users to debug webhooks, retry events, and manage subscriptions.
    • Failure Notifications: Sends Email or Slack notifications when endpoints fail consecutively and are disabled.

  4. Install and run golangci-lint for Tiger Style compliance

    main

    To maintain Tiger Style compliance in your local development environment, install golangci-lint and use it to run the project's configured linting rules. The project treats all warnings as errors to ensure strict adherence to safety, performance, and developer experience principles.

    # Install golangci-lint
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Run linting
golangci-lint run

# Run with specific linters
golangci-lint run --enable=revive,staticcheck

# Fix auto-fixable issues
golangci-lint run --fix

  7. Create an endpoint using the Ruby SDK

    main

    After setting up Convoy, you can create an endpoint by instantiating a Convoy::Endpoint object with a data hash and calling the .save method. An endpoint represents a target URL that will receive events.

    endpoint = Convoy::Endpoint.new(
  data: {
    name: "Endpoint name",
    "description": "Endpoint One",
    "http_timeout": "1m",
    "url": "https://webhook.site/73932854-a20e-4d04-a151-d5952e873abd"
  }
)

endpoint_response = endpoint.save

  8. Linter Exclusions for Tests and Generated Code

    main

    To reduce noise, certain files are exempt from specific Tiger Style constraints:

    • Test Files: Function length and complexity limits are relaxed. All linters are disabled for test data directories.
    • Generated Code: All linters are disabled for generated code. Mock files are excluded from most checks.
    • Command/Migration Files: Function length limits are relaxed for main command files and migration files.

  11. Set up Google OAuth for Convoy

    main

    To enable Google OAuth authentication in Convoy using Google Identity Services (GIS), follow these steps:

    1. Google Cloud Console Configuration

    1. Create or select a project in the Google Cloud Console.
    2. Navigate to APIs & Services → Credentials.
    3. Click Create Credentials → OAuth 2.0 Client IDs and select Web application.
    4. Configure the following:
      • Authorized JavaScript Origins: Add http://localhost and http://localhost:5005 (or your production domain).
      • Authorized Redirect URIs: Add http://localhost:5005/ui/auth/google/callback (or your production callback URL).
    5. Copy the generated Client ID.

    2. Convoy Configuration

    Configure Convoy using either a convoy.json file or environment variables. Note: Google OAuth requires an enterprise license with the GOOGLE_OAUTH feature enabled.

    3. Testing

    1. Start your service (ensure it is running on port 5005 if using the bundled UI):
      cd /path/to/convoy
./server
    2. Navigate to http://localhost:5005 and click Sign in with Google.
    # Example startup command
cd /path/to/convoy
./server