Webhooks

Webhooks are a way for The Formance Platform to send notifications to your application when certain events occur. For example, you can use webhooks to notify your application when a ledger transaction is created, or when a payment is received.

Creating a Webhook

fctl

fctl webhooks create "https://example.com/webhook" "ledger.committed_transactions"

curl

STACK="stack_123" \
curl -X POST \
  https://$STACK.formance.cloud/api/webhooks/configs
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "endpoint": "https://example.com/webhook",
    "eventTypes": ["ledger.committed_transactions"]
}'

Webhook Events

The following events are available for webhooks:

Service	Event
ledger	ledger.committed_transactions
ledger	ledger.saved_metadata
ledger	ledger.updated_mapping
ledger	ledger.reverted_transaction
payments	payments.saved_payment

Webhook Signature

The Formance Platform will sign each webhook request with a signature header. This signature can be used to verify that the request was sent by The Formance Platform. For each configured webhook, a secret key will be generated. This secret key can be retrieved directly from the webhook information:

fctl webhooks list

And can be verified using the following code:

Go

package example

import (
	"io"
	"net/http"
	"strconv"

	"github.com/formancehq/webhooks/pkg/security"
)

func VerifyWebhook(r *http.Request, mySecret string) (bool, error) {
	id := r.Header.Get("formance-webhook-id")
	ts := r.Header.Get("formance-webhook-timestamp")
	signatures := r.Header.Get("formance-webhook-signature")
	timeInt, err := strconv.ParseInt(ts, 10, 64)
	if err != nil {
		return false, err
	}

	payload, err := io.ReadAll(r.Body)
	if err != nil {
		return false, err
	}

	isVerified, err := security.Verify(signatures, id, timeInt, mySecret, payload)
	if err != nil {
		return false, err
	}

	return isVerified, nil
}