Convoy SDK for JS

This is the Convoy JS SDK. This SDK contains methods for easily interacting with Convoy's API. Below are examples to get you started. You can view the full API Reference here

Installation

Install convoy.js

npm install convoy.js

Setup Client

Next, require the convoy module and set it up with your instance URL, API key, and project ID. Both the API key and project ID are 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

// HTTP Client
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' })

// Amazon SQS Client
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', sqs_options: {} })


// Apache Kafka Client
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', kafka_options: {} })

Create an Endpoint

An endpoint represents a target URL to receive events.

const endpointData = {
  name: 'Default Endpoint',
  url: "https://webhook.site/63baf442-bbf7-4d51-97e8-428ade404459",
  description: "Default Endpoint",
  secret: "endpoint-secret",
  events: ["*"]
};

const response = await convoy.endpoints.create(endpointData);

Store the Endpoint ID, so you can use it in subsequent requests for creating subscriptions or sending events.

Creating Subscriptions

const subscription = await convoy.subscriptions.create({
  endpoint_id: '01HD6PJBQ0WE842PZ3J8SHDC46',
  name: 'Test Subscription',
  type: 'api'
});

Sending an Event

You can send events to Convoy via HTTP or via any supported message broker. See here to see the list of supported brokers.

// Send an event to a single endpoint.
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);

// Fanout an event to multiple endpoints.
const fanoutData = {
  owner_id: "some_unique_key",
  event_type: "payment.success",
  data: {
    event: "payment.success",
    data: {
      status: "Completed",
      description: "Transaction Successful",
      userID: "test_user_id808",
    }
  }
};

const fanoutResponse = await convoy.events.createFanOutEvent(fanoutData);

// Broadcast an event to every endpoint in the project.
const broadcastData = {
  event_type: "payment.success",
  data: {
    status: "Completed",
    description: "Transaction Successful",
  }
};

const broadcastResponse = await convoy.events.createBroadcastEvent(broadcastData);

Note: The body struct used above is the same used for the message brokers below.

SQS

This library depends on aws-sdk-js-v3 to configure the SQS client.

// Send event to a single endpoint.
const data = await convoy.sqs.writeEvent({
    endpoint_id: '01HCF8X23MWXCEWR3K3HB7KAY8',
    event_type: '*',
    data: {
        event: "payment.success",
        data: {
            status: "Completed",
            description: "Transaction Successful",
            userID: "test_user_id808",
        }
    }
});

// Fanout an event to multiple endpoints.
const data = await convoy.sqs.writeEvent({
    owner_id: 'some_unique_key',
    event_type: '*',
    data: {
        event: "payment.success",
        data: {
            status: "Completed",
            description: "Transaction Successful",
            userID: "test_user_id808",
        }
    }
});

Kafka

This library depends on kafkajs to configure the Kafka client.

// Send event to a single endpoint.
const data = await convoy.kafka.writeEvent({
  endpoint_id: '01HCF8X23MWXCEWR3K3HB7KAY8',
  event_type: '*',
  data: { 
    event: "payment.success",
    data: {
      status: "Completed", 
      description: "Transaction Successful",
      userID: "test_user_id808",
    }
  }
});

// Fanout an event to multiple endpoints.
const data = await convoy.kafka.writeEvent({
  owner_id: 'some_unique_key',
  event_type: '*',
  data: { 
    event: "payment.success",
    data: {
      status: "Completed",
      description: "Transaction Successful",
      userID: "test_user_id808",
    }
  }
});

Verifying Webhooks

This client supports verifying simple and advanced webhook signatures.

// verfiy a simple signature
const webhook = new Webhook({
    header: '666060cbe1348bbc7ec98f4e93dda8eaaf11bbf283d6a2dd56e841b2ef12fcd465c846903f709942473e1442604798186746f04848702c44a773f80672de7b21',
    payload: { email: 'test@gmail.com', first_name: 'test', last_name: 'test' },
    secret: '8IX9njirDG',
    hash: 'sha512',
    encoding: 'hex',
});

webhook.verify()

// verfiy an advanced signature
const webhook = new Webhook({
    header: 't=2048976161,v1=afdb90313acfa15a3fc425755ae651a204947710315bb2a90bccaa87fce88998,v1=fLBDCBUiX5iIs0L5zfNq45h23EkX1HAMpFF+2lHrnes=',
    payload: { email: 'test@gmail.com' },
    secret: '8IX9njirDG',
    hash: 'sha256',
    encoding: 'base64',
});

expect(webhook.verify()).toBeTruthy();

Testing

npm run test

Contributing

Please see CONTRIBUTING for details.

Credits

• Frain

License

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