TheLazy.Dev
Portfolio GitHub

Blog

cloud |cloudnative |infrastructure |webhooks

Publish An Event to Multiple Endpoints using Convoy

danvixent

Daniel Oluojomu

Posted on March 11, 2022

Publish An Event to Multiple Endpoints using Convoy

One common scenario in publishing webhook events is enabling a user to provide multiple endpoints to receive events. One easy example of this is publishing an event that the user needs to process at more than one location. This location could be a no-code platform like zapier, a newly minted microservice or serverless function, or a good old slack notification. In this article, I’d like to explain how you can achieve this using Convoy.

Infrastructure Representation

Without Convoy, your users have to build in the fan-out mechanism themselves which is a lot more stressful.

Steps

Start Convoy Instance

To follow through with this article you’d need to run an instance of Convoy:

$ docker run \
    -p 5005:5005 \
    --name convoy-server \
    -v `pwd`/convoy.json:/convoy.json \
    ghcr.io/frain-dev/convoy:v0.4.18
Enter fullscreen mode Exit fullscreen mode

Create an Application

Next, we have to create an application under this group.

Sample Payload

{
  "name": "test-app",
  "support_email": "test@gmail.com",
  "secret": "eyJhbGciOiJIUzI1NiJ9"
}
Enter fullscreen mode Exit fullscreen mode

Bash

$ curl \
    --request POST \
    --data @app.json \
    -H "Content-Type: application/json" \
    http://localhost:5005/api/v1/applications
Enter fullscreen mode Exit fullscreen mode

Response

{
    "status": true,
    "message": "App created successfully",
    "data": {
        "uid": "2b1e9973-ed03-403c-a8b0-341edd51fb14",
        "group_id": "f0a187f4-edaa-4f8e-adec-75b9a36b3c68",
        "name": "test-app",
        "support_email": "test@gmail.com",
        "endpoints": [],
        "created_at": "2022-03-09T14:17:51.111+01:00",
        "updated_at": "2022-03-09T14:17:51.111+01:00",
        "events": 0
    }
}
Enter fullscreen mode Exit fullscreen mode

Create Two Endpoints

Now we can create multiple endpoints under this app. The first endpoint will take the * event type. Essentially this event type means all incoming events to that app will be published to that endpoint. The second endpoint will take the event type payment.created. Only incoming with the exact type payment.created will be published to that endpoint. Convoy tries to match the event type to all available endpoints under that app, the event is then published to all the matched endpoints.

For the first endpoint:

Sample Payload

{
  "description": "test-endpoint-1",
  "events": [
    "*"
  ],
  "secret": "12345",
  "url": "<your-endpoint>"
}
Enter fullscreen mode Exit fullscreen mode

Bash

$ curl \
    --request POST \
    --data @endpoint-1.json \
    -H "Content-Type: application/json" \
    http://localhost:5005/api/v1/applications/{appID}/endpoints
Enter fullscreen mode Exit fullscreen mode

Response

{
    "status": true,
    "message": "App endpoint created successfully",
    "data": {
        "uid": "2901bbc9-092e-4685-868d-a17298fe86ba",
        "target_url": "<your-endpoint>",
        "description": "test-endpoint-1",
        "status": "active",
        "secret": "12345",
        "events": [
            "*"
        ],
        "created_at": "2022-03-09T14:18:14.493+01:00",
        "updated_at": "2022-03-09T14:18:14.493+01:00"
    }
}
Enter fullscreen mode Exit fullscreen mode

For the second endpoint:

Sample Payload

{
  "description": "test-endpoint-2",
  "events": [
    "payment.created"
  ],
  "secret": "12345",
  "url": "<your-endpoint>"
}
Enter fullscreen mode Exit fullscreen mode

Bash

$ curl \
    --request POST \
    --data @endpoint-2.json \
    -H "Content-Type: application/json" \
    http://localhost:5005/api/v1/applications/{appID}/endpoints
Enter fullscreen mode Exit fullscreen mode

Response

{
    "status": true,
    "message": "App endpoint created successfully",
    "data": {
        "uid": "2901bbc9-092e-4685-868d-a17298fe86ba",
        "target_url": "<your-endpoint>",
        "description": "test-endpoint-2",
        "status": "active",
        "secret": "12345",
        "events": [
            "payment.created"
        ],
        "created_at": "2022-03-09T14:18:14.493+01:00",
        "updated_at": "2022-03-09T14:18:14.493+01:00"
    }
}
Enter fullscreen mode Exit fullscreen mode

Publish Event

Now let us publish an event with the type payment.created to this app. The payment.created will match both endpoints, since * will match all event types, and the payment.created type of the second endpoint matches exactly.

Sample Payload

{
  "app_id": "2b1e9973-ed03-403c-a8b0-341edd51fb14",
  "data": {
        "blog":"medium.com"
    },
  "event_type": "payment.created"
}
Enter fullscreen mode Exit fullscreen mode

Bash

$ curl \
    --request POST \
    --data @event.json \
    -H "Content-Type: application/json" \
    http://localhost:5005/api/v1/events
Enter fullscreen mode Exit fullscreen mode

Response

{
    "status": true,
    "message": "App event created successfully",
    "data": {
        "uid": "ddcd3928-1d7e-4527-901f-47673fd569ce",
        "event_type": "payment.created",
        "matched_endpoints": 2,
        "provider_id": "",
        "data": {
            "blog": "medium.com"
        },
        "app_metadata": {
            "uid": "2b1e9973-ed03-403c-a8b0-341edd51fb14",
            "title": "test-app",
            "group_id": "e6bbde4b-4c43-45a6-8d4c-c8eed1c2bb41",
            "support_email": "test@gmail.com"
        },
        "created_at": "2022-03-09T15:14:27.569+01:00",
        "updated_at": "2022-03-09T15:14:27.569+01:00"
    }
}
Enter fullscreen mode Exit fullscreen mode

Show Endpoint Response

Illustration of the events coming through

Footnote

This article was originally published on our main blog. Check it out for more articles about convoy!

💖 💪 🙅 🚩
danvixent
Daniel Oluojomu

Posted on March 11, 2022

Join Our Newsletter. No Spam, Only the good stuff.

Sign up to receive the latest update from our blog.

Related

Publish An Event to Multiple Endpoints using Convoy
cloud Publish An Event to Multiple Endpoints using Convoy

March 11, 2022