Webhooks - Formance Documentation

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"

POST/api/webhooks/configs

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

GET/api/webhooks/configs

And can be verified using the following code:

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
}

Service

Event

ledger

ledger.committed_transactions

ledger

ledger.saved_metadata

ledger

ledger.updated_mapping

ledger

ledger.reverted_transaction

payments

payments.saved_payment

Webhook Signature#

fctl webhooks list

GET/api/webhooks/configs

And can be verified using the following code:

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
}