Payment Notifications Webhook

If you run the ACH yourself, Rightfoot tells you who to debit. Every morning it checks your enrolled borrowers’ balances, and sends one signed batch to your webhook listing the borrowers whose balance covers the payment. You debit them through your own setup, then report the outcomes.

Before you start

Register your webhook URL as your default ACH key, and store the signing_secret from the response. It is shown only once.
Enroll borrowers. Your collection policy and any policy_overrides decide when a balance is high enough.
If your endpoint restricts inbound traffic by IP, allowlist Rightfoot’s IPs.

How it works

Each morning at 7:30 a.m. ET, Rightfoot starts checking the balances of your enrolled borrowers.
Once those checks finish, it sends one batch for the day. Every borrower whose balance cleared is in it, with the amount to debit and the balance it saw.
You run the ACH for each entry, for amount_cents, on the debit_by date. Store payment_reference with the payment in your system. It does not need to go on the ACH entry itself.
You report each outcome with Report Payment Results, keyed on payment_reference: settled, returned with its R-code and return date, or not_attempted if you did not run it.

A batch is sent every day, even when nobody cleared. An empty notifications list means a quiet day. No batch at all means something is wrong.

Payload

{
  "type": "payment_notifications.batch",
  "batch_id": "6f1c2a7e-3b4d-4e8f-9a01-b2c3d4e5f607",
  "created_at": "2026-11-10T13:12:04Z",
  "notifications": [
    {
      "payment_reference": "rfpay-retry-3f9a6c1e-2b7d-4c8e-9f10-a1b2c3d4e5f6",
      "borrower_id": "1a2b3c4d",
      "obligation_ref": null,
      "amount_cents": 42500,
      "balance_cents": 118734,
      "balance_read_at": "2026-11-10T12:41:19Z",
      "debit_by": "2026-11-10"
    }
  ]
}

Field	Description
`type`	Always `payment_notifications.batch`
`batch_id`	Identifies this batch. The same on every delivery attempt; use it to ignore a batch you have already processed
`created_at`	When the batch was put together (UTC)
`notifications`	One entry per debit to run. Empty on a day nobody cleared
`payment_reference`	Rightfoot’s reference for this debit, an opaque string. Store it with the payment, and send it as `reference` when you report the outcome
`borrower_id`	The `authorizer_unique_id` you enrolled the borrower with
`obligation_ref`	For a borrower enrolled with `obligations`, the `id` of the obligation this debit collects. `null` otherwise
`amount_cents`	The amount to debit, in cents. `42500` is $425.00
`balance_cents`	The balance Rightfoot read that cleared the debit, in cents
`balance_read_at`	When that balance was read (UTC)
`debit_by`	The date (ET) the debit was decided. Run it that day: the balance was read that morning

Verifying the signature

Each request carries a Rightfoot-Signature header:

Rightfoot-Signature: t=1762780324,v1=5d2f0c...e91a

t is the Unix time the request was sent. v1 is the hex HMAC-SHA256, keyed with your signing_secret, of t, a period, and the raw request body. To verify a request:

Split the header on , and read t and v1.
Compute the HMAC over <t>.<raw body>, using the body exactly as received, before any JSON parsing.
Compare it to v1 with a constant-time comparison.
Reject the request if t is more than a few minutes old, so a captured request cannot be replayed.

Python

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify(signing_secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    timestamp, signature = parts["t"], parts["v1"]
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(
        signing_secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Responding and retries

Respond with any 2xx status once you have stored the batch. Rightfoot does not follow redirects, and waits up to 30 seconds for a response. Anything else, a timeout included, is retried with backoff for about two hours. A batch still undelivered after that is held and sent again the next morning, under the same batch_id, before that day’s batch. Every attempt is signed again with a fresh t; the body is the same each time.

Delivery is at least once. You can receive the same batch_id more than once, so check whether you have already processed it before running any debits.

Reporting outcomes

Until you report an outcome for a payment_reference, Rightfoot treats that debit as in flight and does not notify you about that borrower again. Report every debit in the batch, including the ones you did not run (not_attempted). Upload results at least once a day. Each upload, even one with only the header row, tells Rightfoot your results are current. If no upload arrives for 36 hours, Rightfoot stops notifying you of new debits until one does.

Rotating the secret or changing the URL

To change the URL or rotate the secret, replace the key’s credentials with credentials: {"url": "..."}. The response carries a new signing_secret, and every request from then on is signed with it. The previous secret stops being used immediately, so update your endpoint as soon as you have the new one.

Headers

Rightfoot-Signature

string

required

t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>", keyed with your signing_secret>

Body

application/json

type

enum<string>

Available options:

payment_notifications.batch

batch_id

string<uuid>

The same on every delivery attempt. Use it to ignore a batch already processed.

created_at

string<date-time>

notifications

object[]

One entry per debit to run. Empty on a day nobody cleared.

Show child attributes

Getting Started

On Demand Balance Checks

Monitoring

Payments

Webhooks

Payment Notifications

Payment Notifications Webhook

Before you start

How it works

Payload

Verifying the signature

Responding and retries

Reporting outcomes

Rotating the secret or changing the URL

Headers

Body

​Payment Notifications Webhook

​Before you start

​How it works

​Payload

​Verifying the signature

​Responding and retries

​Reporting outcomes

​Rotating the secret or changing the URL

Headers

Body

Payment Notifications Webhook

Before you start

How it works

Payload

Verifying the signature

Responding and retries

Reporting outcomes

Rotating the secret or changing the URL