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 webhooks create "https://example.com/webhook" "ledger.committed_transactions"

Webhook Events

The following events are available for webhooks:

ServiceEvent
ledgerledger.committed_transactions
ledgerledger.saved_metadata
ledgerledger.updated_mapping
ledgerledger.reverted_transaction
paymentspayments.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:

verify-webhook.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
}