This is the Convoy JS SDK. This SDK contains methods for easily interacting with Convoy's API. Below are examples to get you started. For additional examples, please see our official documentation at (https://convoy.readme.io/reference)
Install convoy.js
npm install convoy.js
Next, require the convoy
module and setup with your auth credentials.
// HTTP Client which connects to Convoy Cloud
const { Convoy } = require('convoy.js');
const convoy = new Convoy({ api_key: 'your_api_key', project_id: 'your_project_id' })
// HTTP Client which connects to a self hosted Convoy instance
const { Convoy } = require('convoy.js');
const convoy = new Convoy({ uri: "http://your-host/api/v1", api_key: 'your_api_key', project_id: 'your_project_id' })
// Amazon SQS Client
const { Convoy } = require('convoy.js');
const convoy = new Convoy({ api_key: 'your_api_key', project_id: 'your_project_id', sqsOptions: {} })
// Apache Kafka Client
const { Convoy } = require('convoy.js');
const convoy = new Convoy({ api_key: 'your_api_key', project_id: 'your_project_id', kafkaOptions: {} })
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.
const subscription = await convoy.subscriptions.create({
endpoint_id: '01HD6PJBQ0WE842PZ3J8SHDC46',
name: 'Test Subscription',
type: 'api'
});
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 eventData = {
owner_id: "some_unique_key",
event_type: "payment.success",
data: {
event: "payment.success",
data: {
status: "Completed",
description: "Transaction Successful",
userID: "test_user_id808",
}
}
};
const response = await convoy.events.createFanOutEvent(eventData);
Note: The body struct used above is the same used for the message brokers below.
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",
}
}
});
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",
}
}
});
This client supports verifying simple and advanced webhook signatures.
// verfiy a simple signature
const webhook = new Webhook({
header: '666060cbe1348bbc7ec98f4e93dda8eaaf11bbf283d6a2dd56e841b2ef12fcd465c846903f709942473e1442604798186746f04848702c44a773f80672de7b21',
payload: { email: '[email protected]', 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: '[email protected]' },
secret: '8IX9njirDG',
hash: 'sha256',
encoding: 'base64',
});
expect(webhook.verify()).toBeTruthy();
npm run test
Please see CONTRIBUTING for details.
The MIT License (MIT). Please see License File for more information.