Skip to main content
Version: v2.0

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 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:

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
}