This is the Golang SDK for Convoy. It makes it easy to interact with the Convoy API. You can view the full API Reference here
$ go get github.com/frain-dev/convoy-go/v2To begin you need to define a Client.
Below are the several ways you can configure a client depending on your needs.
baseURL := "{host}/api/v1"
// Regular Client
c := convoy.New(baseURL, apiKey, projectID)
// Add a Custom HTTP Client
client := &http.Client{}
c := convoy.New(baseURL, apiKey, projectID,
convoy.OptionHTTPClient(client))
// Add a SQS Client
so := &convoy.SQSOptions{
Client: sqs.New(),
QueueUrl: "queue-url",
}
c := convoy.New(baseURL, apiKey, projectID,
convoy.OptionSQSOptions(so))
// Add a Kafka Client
ko := &convoy.KafkaOptions{
Client: &kafka.Client{},
Topic: "kafka-topic",
}
c := convoy.New(baseURL, apiKey, projectID,
convoy.OptionKafkaOptions(ko))Please see go reference for other options available to use to configure your client.
body := &convoy.CreateEndpointRequest{
Name: "endpoint-name",
URL: "http://play.getconvoy.io/ingest/DQzxCcNKTB7SGqzm",
Secret: "endpoint-secret",
SupportEmail: "notifications@getconvoy.io"
}
endpoint, err := c.Endpoints.Create(ctx, body, nil)
if err != nil {
return err
}Store the Endpoint ID, so you can use it in subsequent requests for creating subscriptions or sending events.
body := &convoy.CreateSubscriptionRequest{
Name: "endpoint-subscription",
EndpointID: "endpoint-id",
FilterConfig: &convoy.FilterConfiguration{
EventTypes: []string{"*"},
},
}
subscription, err := c.Subscriptions.Create(ctx, body)
if err != nil {
return err
}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.
body := &CreateEventRequest{
EventType: "event.type",
EndpointID: "endpoint-id",
IdempotencyKey: "unique-event-id",
Data: []byte(`{"version": "Convoy v24.0.0"}`),
}
event, err := c.Events.Create(ctx, body)
if err != nil {
return err
}
// Send event to multiple endpoints.
body := &CreateFanoutEventRequest{
EventType: "event.type",
OwnerID: "unique-user-id",
IdempotencyKey: "unique-event-id",
Data: []byte(`{"version": "Convoy v24.0.0"}`),
}
event, err := c.Events.FanoutEvent(ctx, body)
if err != nil {
return err
}Note: The body struct used above is the same used for the message brokers below.
// Send event to a single endpoint.
err := c.SQS.WriteEvent(ctx, body)
if err != nil {
return err
}
// Send event to multiple endpoints.
err := c.SQS.WriteFanoutEvent(ctx, body)
if err != nil {
return err
}This library depends on kafka-go to configure Kafka Clients.
// Send event to a single endpoint.
err := c.Kafka.WriteEvent(ctx, body)
if err != nil {
return err
}
// Send event to multiple endpoints.
err := c.Kafka.WriteFanoutEvent(ctx, body)
if err != nil {
return err
}This client supports verifying simple and advanced webhook signatures.
webhook := NewWebhook(&convoy.ConfigOpts{
SigHeader: "ZmBgy+E0i7x+yY9Ok92P3CZQkc+FEJgR5gYZ0bwSEhwLESnc/gGct57IQ==",
Payload: []byte(`{"firstname":"test","lastname":"test"}`),
Secret: "8IX9njirDG",
Hash: "SHA512",
Encoding: "base64",
})
err := webhook.Verify()
if err != nil {
return err
}The following table identifies which version of the Convoy API is supported by this (and past) versions of this repo (convoy-go)
| convoy-go Version | Convoy API Version |
|---|---|
| v2.1.5 | 0001-01-01 |
| v2.1.6 | 0001-01-01 |
| v2.1.7 | 0001-01-01 |
The MIT License (MIT). Please see License File for more information.