Send Webhook Events

In this guide, you’ll learn how to deploy your first webhook event with Convoy. You’ll be making use of your project API key which can be generated by creating a project from your dashboard. You’ll also need your project ID which can be retrieved from your Project Settings page.

Install Client

Install convoy.js with:

terminal
npm install convoy.js

Configure

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

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'
});

Now that your client has been configured, create a convoy application.

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);
}

The next step is to create a subscription to the webhook source. Subscriptions are the conduit through which events are routed from a source to a destination on Convoy.

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

	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

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

example
try {
	const eventData = {
		endpoint_id: endpoint_id,
		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

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

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'
});

Now that your client has been configured, create a convoy application.

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);
}

The next step is to create a subscription to the webhook source. Subscriptions are the conduit through which events are routed from a source to a destination on Convoy.

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

	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

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

example
try {
	const eventData = {
		endpoint_id: endpoint_id,
		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.rb with:

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

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: "<your endpoint>",
    Description: "<endpoint description>",
}, nil)

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

The next step is to create a subscription to the webhook source. Subscriptions are the conduit through which events are routed from a source to a destination on Convoy.

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 you 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)
}

Sending webhooks with the API does not require a client setup like the SDKs. The API key retrieved from your dashboard will be added to the Authorization header and the project ID will be added to the request URL.

Create an Endpoint

An endpoint is a specific destination that can receive webhook events. Once you create an endpoint, you’ll receive a uid as part of the response that you should save and supply in subsequent API calls to perform other requests such as creating an event.

terminal
curl --request POST \
  --url https://dashboard.getconvoy.io/api/v1/projects/<project-id>/endpoints \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
    {
      "name": "Convoy endpoint",
      "description": "Endpoint description",
      "http_timeout": "10s",
      "url": "https://webhook.site/40984a4e-7b36-41fb-a234-9c2006bac8b5"
  }'

The next step is to create a subscription to the webhook source. Subscriptions are the conduit through which events are routed from a source to a destination on Convoy.

terminal
curl --request POST \
  --url https://dashboard.getconvoy.io/api/v1/projects/<project-id>/subscriptions \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "endpoint_id": <endpoint-id>,
    "name": "Subscription name"
}'

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 you created earlier.

terminal
curl --request POST \
  --url https://dashboard.getconvoy.io/api/v1/projects/<project-id>/events \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "endpoint_id": "<endpoint-id>",
    "event_type": "payment.success",
    "data": {
      "event": "payment.success",
      "data": {
        "status": "Completed",
        "description": "Transaction Successful",
        "userID": "test_user_id808"
      }
    }
}'

Cheers! 🎉

You have successfully created a Convoy application to send events to your configured endpoint.

Home

Guides

Deployment

Product Manual

Command Line

SDK

Cloud

Legal

Business & Enterprise

Resources

FAQ

Send Your First Webhook Event

Install Client

Configure

Create an Endpoint

Send an Event

Install Client

Configure

Create an Endpoint

Send an Event

Install Client

Configure

Create an Endpoint

Send an Event

Install Client

Configure

Create an Endpoint

Send an Event

Create an Endpoint

Send an Event

Cheers! 🎉

Home

Guides

Deployment

Product Manual

Command Line

SDK

Cloud

Legal

Business & Enterprise

Resources

FAQ

​Install Client

​Configure

​Create an Endpoint

​Subscribe for Events

​Send an Event

​Install Client

​Configure

​Create an Endpoint

​Subscribe for Events

​Send an Event

​Install Client

​Configure

​Create an Endpoint

​Subscribe for Events

​Send an Event

​Install Client

​Configure

​Create an Endpoint

​Subscribe for Events

​Send an Event

​Create an Endpoint

​Subscribe for Events

​Send an Event

​Cheers! 🎉

Install Client

Configure

Create an Endpoint

Subscribe for Events

Send an Event

Install Client

Configure

Create an Endpoint

Subscribe for Events

Send an Event

Install Client

Configure

Create an Endpoint

Subscribe for Events

Send an Event

Install Client

Configure

Create an Endpoint

Subscribe for Events

Send an Event

Create an Endpoint

Subscribe for Events

Send an Event

Cheers! 🎉