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 us dashboard or eu dashboard. You’ll also need your project ID which can be retrieved 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
cURL

Install Client

Install convoy.js with:

terminal

npm install convoy.js

Configure

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

Now that your client has been configured, create an endpoint.

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

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: {
			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

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",
})

Now that your client has been configured, create an endpoint.

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"]

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_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

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

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

Install convoy.rb with:

terminal

gem install convoy.rb

Configure

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

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.

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

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

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

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

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://{region}.getconvoy.cloud/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://example.com/webhooks/convoy"
  }'

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://{region}.getconvoy.cloud/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 endpoint you created earlier.

terminal

curl --request POST \
  --url https://{region}.getconvoy.cloud/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.

​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! 🎉