Convoy SDK Documentation

Convoy provides SDK 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 demonstrate the steps involved in sending an event to your Convoy instance.

Install Client

Install convoy.js with

terminal
$ npm install convoy.js

Configure

Next, require the convoy module and setup with your auth credentials.

example
const { Convoy } = require("convoy.js");
const convoy = new Convoy({ api_key: "your_api_key" });

The SDK also supports authenticating via Basic Auth by defining your username and password.

example
const convoy = new Convoy({ username: "default", password: "default" });

In the event you’re using a self hosted convoy instance, you can define the url as part of what is passed into convoy’s constructor.

example
const convoy = new Convoy({
  api_key: "your_api_key",
  uri: "self-hosted-instance",
});

Create an Endpoint

example
try {
  const endpointData = {
    url: "https://0d87-102-89-2-172.ngrok.io",
    description: "Default Endpoint",
    secret: "endpoint-secret",
    events: ["*"],
  },

  const response = await convoy.endpoints.create(appId, 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.

Sending an Event

example
try {
  const eventData = {
    endpoint_id: endpointId,
    event_type: "payment.success",
    data: {
      event: "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.js with

terminal
$ npm install convoy.js

Configure

Next, require the convoy module and setup with your auth credentials.

example
const { Convoy } = require("convoy.js");
const convoy = new Convoy({ api_key: "your_api_key" });

The SDK also supports authenticating via Basic Auth by defining your username and password.

example
const convoy = new Convoy({ username: "default", password: "default" });

In the event you’re using a self hosted convoy instance, you can define the url as part of what is passed into convoy’s constructor.

example
const convoy = new Convoy({
  api_key: "your_api_key",
  uri: "self-hosted-instance",
});

Create an Endpoint

example
try {
  const endpointData = {
    url: "https://0d87-102-89-2-172.ngrok.io",
    description: "Default Endpoint",
    secret: "endpoint-secret",
    events: ["*"],
  },

  const response = await convoy.endpoints.create(appId, 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.

Sending an Event

example
try {
  const eventData = {
    endpoint_id: endpointId,
    event_type: "payment.success",
    data: {
      event: "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

Add this line to your application’s Gemfile:

terminal
$ 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 api_key and project_id, see below:

require 'convoy'

Convoy.ssl = true
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.

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

endpoint_response = endpoint.save

Create an Subscription

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

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 to pass the uid from the endpoint we created earlier.

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

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

  c := convoy.New(convoy.Options{
      APIKey: "your_api_key",
  })

The SDK also supports authenticating via Basic Auth by providing your username and password

example
 c := convoy.New(convoy.Options{
      APIUsername: "default",
      APIPassword: "default",
  })

In the event you’re using a self hosted convoy instance, you can define the url as part of what is passed into the convoy.Options struct

example
c := convoy.New(convoy.Options{
     APIKey: "your_api_key",
     APIEndpoint: "self-hosted-instance",
 })

Create an endpoint

example
endpoint, err := c.Endpoints.Create(app.UID, &Convoy.CreateEndpointRequest{
    URL: "http://localhost:8081",
    Description: "Some description",
}, nil)

  if err != nil {
      log.Fatal("failed to create app endpoint \n", err)
  }

Create a Subscription

example
subscription, err := c.Subscriptions.Create(&Convoy.CreateSubscriptionRequest{
  Name: "<subscription name>"
  EndpointID: "<endpoint-id>"
}, nil)

if err != nil {
    log.Fatal("failed to create app endpoint \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 application we created earlier.

example
event, err := c.Events.Create(&convoy.CreateEventRequest{
        EndpointID: endpoint.UID,
		EventType: "test.customer.event",
		Data:      []byte(`{"event_type": "test.event", "data": { "Hello": "World", "Test": "Data" }}`),
	}, nil)

	if err != nil {
		log.Fatal("failed to create app event \n", err)
	}

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

Resources

FAQ

SDK

Install Client

Configure

Sending an Event

Install Client

Configure

Sending an Event

Install Client

Configure

Create an Endpoint

Create an Subscription

Send an Event

Install Client

Configure

Create an endpoint

Create a Subscription

Send an Event

Don’t miss anything.

Home

Guides

Deployment

Product Manual

Command Line

SDK

Cloud

Legal

Business & Enterprise

Resources

FAQ

​Install Client

​Configure

​Sending an Event

​Install Client

​Configure

​Sending an Event

​Install Client

​Configure

​Create an Endpoint

​Create an Subscription

​Send an Event

​Install Client

​Configure

​Create an endpoint

​Create a Subscription

​Send an Event

​Don’t miss anything.

Install Client

Configure

Sending an Event

Install Client

Configure

Sending an Event

Install Client

Configure

Create an Endpoint

Create an Subscription

Send an Event

Install Client

Configure

Create an endpoint

Create a Subscription

Send an Event

Don’t miss anything.