frain/convoy

Convoy PHP SDK Library

v2.0.0 2026-07-20 20:01 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.3
• guzzlehttp/psr7: ^1.7 || ^2.0
• php-http/client-common: ^2.5
• php-http/discovery: ^1.14
• psr/http-client: ^1.0
• psr/http-client-implementation: ^1.0
• psr/http-factory: ^1.0
• symfony/options-resolver: ^6.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• nyholm/psr7: ^1.8
• pestphp/pest: ^3.0
• php-http/curl-client: ^2.2
• php-http/mock-client: ^1.6

MIT

• Frain

• webhooks
• frain
• convoy

Published on Packagist.org on 2026-07-21 12:39 UTC

README

This is the Convoy PHP SDK. This SDK contains methods for easily interacting with Convoy's API. Below are examples to get you started. See our API Reference for more.

Installation

To install the package, you will need to be using Composer in your project.

The Convoy PHP SDK is not hard coupled to any HTTP Client such as Guzzle or any other library used to make HTTP requests. The HTTP Client implementation is based on PSR-18. This provides you with the convenience of choosing what PSR-7 and HTTP Client you want to use.

To get started quickly,

composer require frain/convoy symfony/http-client nyholm/psr7

Generated API client (Convoy\Client)

The Convoy\Client namespace (src/Client/) is generated from Convoy's OpenAPI spec via OpenAPI Generator and covers the full /api/v1 surface with typed models (Guzzle-based):

use Convoy\Client\Api\EventsApi;
use Convoy\Client\Configuration;
use Convoy\Client\Model\ModelsCreateEvent;

$config = (new Configuration())
    ->setHost('https://us.getconvoy.cloud/api')
    ->setAccessToken($apiKey); // the client adds the Bearer prefix

// Pin the API version this client was generated from.
$http = new \GuzzleHttp\Client([
    'headers' => ['X-Convoy-Version' => '2025-11-24'],
]);

$events = new EventsApi($http, $config);
$events->createEndpointEvent($projectId, (new ModelsCreateEvent())
    ->setEndpointId('endpoint-id')
    ->setEventType('invoice.paid')
    ->setData(['amount' => 100, 'currency' => 'USD']));

Do not edit src/Client/ by hand; regenerate with ./scripts/generate.sh (CI on frain-dev/convoy dispatches this when the spec changes). The hand-written SDK below (incl. webhook verify) is never touched by generation.

Setup Client

Set up the client with your instance URL, API key, and project ID. Both the API key and project ID are available from your Project Settings page.

use Convoy\Convoy;

$convoy = new Convoy([
    "uri" => "https://us.getconvoy.cloud/api/v1",
    "api_key" => "your_api_key",
    "project_id" => "your_project_id"
]);

Your instance URL depends on where your project lives:

• Convoy Cloud (US): https://us.getconvoy.cloud/api/v1
• Convoy Cloud (EU): https://eu.getconvoy.cloud/api/v1
• Self-hosted: https://your-instance/api/v1

Create an Endpoint

An endpoint represents a target URL to receive events.

$endpointData = [
    "name" => "default-endpoint",
    "url" => "https://example.com/webhooks/convoy",
    "description" => "Default Endpoint",
    "secret" => "endpoint-secret"
];

$response = $convoy->endpoints()->create($endpointData);
$endpointId = $response["data"]["uid"];

Create a Subscription

Subscriptions route events from a source to an endpoint.

$subscriptionData = [
    "name" => "event-sub",
    "endpoint_id" => $endpointId
];

$response = $convoy->subscriptions()->create($subscriptionData);

Sending an Event

To send an event, you'll need the uid from the endpoint we created earlier.

$eventData = [
    "endpoint_id" => $endpointId,
    "event_type" => "payment.success",
    "data" => [
        "status" => "Completed",
        "description" => "Transaction Successful"
    ]
];

$response = $convoy->events()->create($eventData);

To fan an event out to all endpoints with the same owner_id, or broadcast to every endpoint in the project:

$response = $convoy->events()->fanout(["owner_id" => "owner-1", "event_type" => "payment.success", "data" => []]);
$response = $convoy->events()->broadcast(["event_type" => "payment.success", "data" => []]);

Verifying Webhook Signatures

Verify with the raw request body, before parsing it. Always check the return value: verify returns false for an invalid simple signature, and throws WebhookVerificationException for invalid advanced signatures and malformed headers.

use Convoy\Webhook;

$webhook = new Webhook("endpoint-secret");

try {
    $valid = $webhook->verify($rawRequestBody, $_SERVER["HTTP_X_CONVOY_SIGNATURE"]);
} catch (\Convoy\Exceptions\WebhookVerificationException $e) {
    $valid = false;
}

if ($valid !== true) {
    http_response_code(400);
    exit;
}

// signature is valid; process the event

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Credits

• Frain

License

The MIT License (MIT). Please see License File for more information.