Go SDK

meridian-go - the official Go client: installation, context-aware methods, iterators, option structs, and webhook verification.

Last updated August 26, 20262 min readEdit page

On this page

The official Go client for Go 1.21+. Context-first API design, iterator-based pagination, typed params via option structs, and a webhook subpackage for signature verification.

Installation

TerminalShell

go get github.com/meridian/meridian-go/v2

Initialization

main.goGo

package main

import (
    "os"

    "github.com/meridian/meridian-go/v2"
)

func main() {
    client := meridian.NewClient(os.Getenv("MERIDIAN_API_KEY"))
    _ = client
}

With options:

options.goGo

client := meridian.NewClient(
    os.Getenv("MERIDIAN_API_KEY"),
    meridian.WithTimeout(30*time.Second),
    meridian.WithMaxRetries(3),
    meridian.WithHTTPClient(customHTTPClient),
)

Methods

Every method takes context.Context first and returns typed results:

projects.goGo

project, err := client.Projects.Create(ctx, &meridian.ProjectCreateParams{
    Name:   "billing-sync",
    Region: "us-east",
})
if err != nil {
    var merr *meridian.Error
    if errors.As(err, &merr) {
        log.Printf("failed: %s %s (req %s)", merr.Code, merr.Message, merr.RequestID)
    }
    return err
}

Method	Endpoint
`Projects.Create(ctx, params)`	`POST /projects`
`Projects.Get(ctx, id)`	`GET /projects/:id`
`Projects.Update(ctx, id, params)`	`PATCH /projects/:id`
`Projects.Delete(ctx, id)`	`DELETE /projects/:id`
`Projects.List(ctx, params)`	`GET /projects` (iterator)
`Webhooks.Create / List / Deliveries / Replay`	`/webhooks*`
`Events.List / Get`	`/events*`

Pagination

List returns an iterator - no manual cursor handling:

iterate.goGo

it := client.Projects.List(ctx, &meridian.ProjectListParams{
    Status: meridian.String("active"),
})
for it.Next() {
    p := it.Current()
    fmt.Println(p.ID, p.Name)
}
if err := it.Err(); err != nil {
    return err
}

Webhook verification

webhook.goGo

import "github.com/meridian/meridian-go/v2/webhook"

event, err := webhook.Verify(
    rawBody,                        // []byte - do NOT unmarshal first
    r.Header.Get("Meridian-Signature"),
    os.Getenv("WEBHOOK_SECRET"),
    webhook.DefaultTolerance,       // 5 minutes
)
if err != nil {
    http.Error(w, "invalid signature", http.StatusBadRequest)
    return
}

Errors

Errors implement *meridian.Error - inspect with errors.As:

errors.goGo

var merr *meridian.Error
if errors.As(err, &merr) {
    merr.Status     // 429
    merr.Code       // "rate_limited"
    merr.RetryAfter // seconds, when Retry-After was sent
    merr.RequestID  // req_…
}

Initialization

main.goGo

package main

import (
    "os"

    "github.com/meridian/meridian-go/v2"
)

func main() {
    client := meridian.NewClient(os.Getenv("MERIDIAN_API_KEY"))
    _ = client
}

With options:

options.goGo

client := meridian.NewClient(
    os.Getenv("MERIDIAN_API_KEY"),
    meridian.WithTimeout(30*time.Second),
    meridian.WithMaxRetries(3),
    meridian.WithHTTPClient(customHTTPClient),
)

Methods

Every method takes context.Context first and returns typed results:

projects.goGo

project, err := client.Projects.Create(ctx, &meridian.ProjectCreateParams{
    Name:   "billing-sync",
    Region: "us-east",
})
if err != nil {
    var merr *meridian.Error
    if errors.As(err, &merr) {
        log.Printf("failed: %s %s (req %s)", merr.Code, merr.Message, merr.RequestID)
    }
    return err
}

Method	Endpoint
`Projects.Create(ctx, params)`	`POST /projects`
`Projects.Get(ctx, id)`	`GET /projects/:id`
`Projects.Update(ctx, id, params)`	`PATCH /projects/:id`
`Projects.Delete(ctx, id)`	`DELETE /projects/:id`
`Projects.List(ctx, params)`	`GET /projects` (iterator)
`Webhooks.Create / List / Deliveries / Replay`	`/webhooks*`
`Events.List / Get`	`/events*`

it := client.Projects.List(ctx, &meridian.ProjectListParams{ Status: meridian.String("active"), }) for it.Next() { p := it.Current() fmt.Println(p.ID, p.Name) } if err := it.Err(); err != nil { return err }

Webhook verification

webhook.goGo

import "github.com/meridian/meridian-go/v2/webhook"

event, err := webhook.Verify(
    rawBody,                        // []byte - do NOT unmarshal first
    r.Header.Get("Meridian-Signature"),
    os.Getenv("WEBHOOK_SECRET"),
    webhook.DefaultTolerance,       // 5 minutes
)
if err != nil {
    http.Error(w, "invalid signature", http.StatusBadRequest)
    return
}

var merr *meridian.Error if errors.As(err, &merr) { merr.Status // 429 merr.Code // "rate_limited" merr.RetryAfter // seconds, when Retry-After was sent merr.RequestID // req_… }