Convoy SDK Documentation

Convoy provides SDKs for in-app integration. These SDKs carry out the same operations as the API and Convoy dashboard. The methods in each SDK mirror the API. This page introduces you to the SDKs as well as demonstrates the steps involved in sending an event to your Convoy instance. You will need your project API key and project ID, both available from your Project Settings page. 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

The Ruby gem is the one exception: it appends /v1 itself, so Convoy.base_uri takes the URL without /v1 (for example https://us.getconvoy.cloud/api). The Ruby tab below shows this.

Javascript
Python
Ruby
Golang

Install Client

Install convoy.js with

terminal

npm install convoy.js

Configure

Next, require the convoy module and set it up with your instance URL, API key, and project ID.

example

const { Convoy } = require('convoy.js');

const convoy = new Convoy({
    uri: 'https://us.getconvoy.cloud/api/v1',
    api_key: 'your_api_key',
    project_id: 'your_project_id'
});

Create an Endpoint

example

try {
    const endpointData = {
        name: 'default-endpoint',
        url: 'https://example.com/webhooks/convoy',
        description: 'Default Endpoint',
        secret: 'endpoint-secret'
    };

    const response = await convoy.endpoints.create(endpointData);
} catch (error) {
    console.log(error);
}

Create a Subscription

example

try {
    const subscriptionData = {
        name: 'event-sub',
        endpoint_id: endpointId
    };

    const response = await convoy.subscriptions.create(subscriptionData);
} catch (error) {
    console.log(error);
}

With the subscription in place, you’re set to send an event.

Send an Event

example

try {
    const eventData = {
        endpoint_id: endpointId,
        event_type: 'payment.success',
        data: {
            status: 'Completed',
            description: 'Transaction Successful',
            userID: 'test_user_id808'
        }
    };

    const response = await convoy.events.create(eventData);
} catch (error) {
    console.log(error);
}

Install Client

Install convoy-python with

terminal

pip install convoy-python

Configure

Next, import the convoy module and set it up with your auth credentials. uri is your instance API base; the client scopes requests to your project automatically.

example

from convoy import Convoy

convoy = Convoy({
    "api_key": "your_api_key",
    "uri": "https://us.getconvoy.cloud/api/v1",
    "project_id": "your_project_id",
})

Create an Endpoint

Each method takes a query dict and returns a (response, status) tuple.

example

endpoint_data = {
    "name": "default-endpoint",
    "url": "https://example.com/webhooks/convoy",
    "description": "Default Endpoint",
    "secret": "endpoint-secret",
}

(response, status) = convoy.endpoint.create({}, endpoint_data)
endpoint_id = response["data"]["uid"]

Create a Subscription

example

subscription_data = {
    "name": "event-sub",
    "endpoint_id": endpoint_id,
}

(response, status) = convoy.subscription.create({}, subscription_data)

With the subscription in place, you’re set to send an event.

Send an Event

example

event_data = {
    "endpoint_id": endpoint_id,
    "event_type": "payment.success",
    "data": {
        "status": "Completed",
        "description": "Transaction Successful",
        "userID": "test_user_id808",
    },
}

(response, status) = convoy.event.create({}, event_data)

Install Client

Add this line to your application’s Gemfile:

example

gem 'convoy.rb'

And then execute:

terminal

bundle install

Or install it yourself as:

terminal

gem install convoy.rb

Configure

To configure your client, provide your instance URL, api_key, and project_id, see below:

example

require 'convoy'

Convoy.base_uri = "https://us.getconvoy.cloud/api"
Convoy.api_key = "CO.M0aBe..."
Convoy.project_id = "23b1..."

Create an Endpoint

An endpoint represents a target URL to receive webhook events. You should create one endpoint per user/business or whatever scope works well for you.

example

endpoint = Convoy::Endpoint.new(
  data: {
    "name": "default-endpoint",
    "description": "Endpoint One",
    "http_timeout": "1m",
    "url": "https://example.com/webhooks/convoy"
  }
)

endpoint_response = endpoint.save

Create a Subscription

After creating an endpoint, we need to subscribe the endpoint to events.

example

subscription = Convoy::Subscription.new(
  data: {
    endpoint_id: endpoint_id,
    name: 'ruby subscription'
  }
)

subscription_response = subscription.save

Send an Event

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

example

event = Convoy::Event.new(
  data: {
    endpoint_id: endpoint_id,
    event_type: "wallet.created",
    data: {
      status: "completed",
      event_type: "wallet.created",
      description: "transaction successful"
    }
  }
)

event_response = event.save

Install Client

Install convoy-go with

terminal

go get github.com/frain-dev/convoy-go/v2

Configure

The client takes your instance URL, API key, and project ID.

example

import (
    "context"

    convoy "github.com/frain-dev/convoy-go/v2"
)

ctx := context.Background()

c := convoy.New("https://us.getconvoy.cloud/api/v1", "your_api_key", "your_project_id")

Create an Endpoint

example

endpoint, err := c.Endpoints.Create(ctx, &convoy.CreateEndpointRequest{
    Name:        "default-endpoint",
    URL:         "https://example.com/webhooks/convoy",
    Description: "Default Endpoint",
}, nil)
if err != nil {
    log.Fatal("failed to create endpoint \n", err)
}

Create a Subscription

example

subscription, err := c.Subscriptions.Create(ctx, &convoy.CreateSubscriptionRequest{
    Name:       "event-sub",
    EndpointID: endpoint.UID,
})
if err != nil {
    log.Fatal("failed to create subscription \n", err)
}

With the subscription in place, you’re set to send an event.

Send an Event

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

example

err = c.Events.Create(ctx, &convoy.CreateEventRequest{
    EndpointID: endpoint.UID,
    EventType:  "payment.success",
    Data:       []byte(`{"status": "Completed", "description": "Transaction Successful"}`),
})
if err != nil {
    log.Fatal("failed to create event \n", err)
}

To verify webhook signatures on the receiving side with these SDKs, see the receiving guide. Contribute to this doc in Github

Don’t miss anything.

Subscribe to the Convoy Newsletter find tutorials and tools that will help you grow as a developer and scale your project or business, and see interesting topics.

Home

Guides

Deployment

Product Manual

Command Line

SDK

Cloud

Legal

Business & Enterprise

Glossary

Resources

FAQ

SDK

Install Client

Configure

Create an Endpoint

Create a Subscription

Send an Event

Install Client

Configure

Create an Endpoint

Create a Subscription

Send an Event

Install Client

Configure

Create an Endpoint

Create a Subscription

Send an Event

Install Client

Configure

Create an Endpoint

Create a Subscription

Send an Event

Don’t miss anything.

​Install Client

​Configure

​Create an Endpoint

​Create a Subscription

​Send an Event

​Install Client

​Configure

​Create an Endpoint

​Create a Subscription

​Send an Event

​Install Client

​Configure

​Create an Endpoint

​Create a Subscription

​Send an Event

​Install Client

​Configure

​Create an Endpoint

​Create a Subscription

​Send an Event

​Don’t miss anything.

Install Client

Configure

Create an Endpoint

Create a Subscription

Send an Event

Install Client

Configure

Create an Endpoint

Create a Subscription

Send an Event

Install Client

Configure

Create an Endpoint

Create a Subscription

Send an Event

Install Client

Configure

Create an Endpoint

Create a Subscription

Send an Event

Don’t miss anything.