Convoy SDK for PHP

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

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.