Webhooks & Events

Lead sends webhooks to notify you about events that happen within your program. We use HTTPS to send events as a JSON payload. You can then use these events to trigger new actions in your system.

Webhook Authentication

To verify a webhook came from Lead, every webhook contains a signature in the header: Lead-Signature. The format of the Lead-Signature header is t={0},v0={1}.

t is the timestamp in milliseconds
v0 is a HMAC signature with SHA-256. It uses the webhook endpoint’s signing secret as the key, and the event payload (the request body) in string bytes as the message.
The hmac portion of the signature header is base64 encoded.

To authenticate a webhook, calculate the HMAC of the t and webhook request body concatenated with ., i.e. base64(HMAC256(t + . + webhook request body)), and ensure it matches v0, the signature sent in the Lead-Signature header.

Ensure to concatenate the webhook request body as bytes (directly as it is received) without any additional processing.

For added security, you can also compare t, the timestamp the webhook was sent to the current timestamp on your server and decide if it’s within your tolerance to prevent a replay attack.

Webhook IP Addresses

Lead will always send webhooks from the following IP addresses:

Production: 3.216.219.186
Sandbox: 34.234.237.195

Replayed & Missed Events

Lead will consider an event successfully delivered once we receive a 2XX HTTP response from your webhook endpoint. If an event delivery receives a non-2XX response, we will retry delivery every three hours until we receive a success response from your endpoint, or we’ve made 24 attempts.

An event may be delivered multiple times to a webhook endpoint.To prevent processing the same event multiple times you can use the unique event id as an idempotency key.

To ensure you haven’t missed any events, use the List all events API to retrieve previous events up to 90 days.

Retrieving an event older than 90 days will result in a 404.

Pairing Webhooks With Reconciliation

Webhooks are the recommended way to receive real-time lifecycle updates, but they should not be your only signal. A polling-only integration is fragile, and a webhook-only integration can miss events. Pair webhooks with a periodic reconciliation pass for the following reasons:

Not every status sends a webhook. Some states are marked Webhook Sent: No in the event tables below (for example, wire.created, ach.processing, ach.pending_return, account_number.activated). You will only observe those states by retrieving the underlying resource (such as GET /v1/wires/{wire_id} or GET /v1/ach/{ach_id}) or by listing events.
Delivery is retried but not guaranteed forever. Failed deliveries retry every three hours up to 24 attempts. After that, the event is not retried.
Events may be delivered more than once. Use the event id as an idempotency key when processing.
Events expire after 90 days. Reconcile before that window closes.

For most programs, the recommended pattern is:

Process webhooks in real time as the primary trigger for downstream logic.
Run a periodic reconciliation job (for example, hourly or daily) that calls List all events and/or the relevant resource endpoint to catch anything missed.
Use the resource endpoint (GET /v1/wires/{wire_id}, GET /v1/ach/{ach_id}, GET /v1/instant_payments/{id}, etc.) when you need the authoritative current status of a single transfer.

Webhook Format

Sample of Lead-Signature header with the hmac value under v0 :

"t=1713350954014,v0=EonRn+iGDCUm+VSc+rR9RVvMOofQDR/bfEJvihRSx6g="

An event body will follow this shape:

{  
    "id": "string",  
    "created_at": "ISO-8601"  
    "object": {hash},  
    "event": "string", 
}

Field	Description
id	A unique identifier for this specific event.
created_at	The ISO-8601 timestamp of when the event object was created.
object	The most up to date version of the object affected by this event.
event	A machine-readable string describing this event.

Event Types

ACH Events

Event	Description	ACH Direction	Webhook Sent
ach.scheduled	The Lead platform has received an incoming ACH and is waiting on settlement to post to your account.	incoming	Yes
ach.processing	The ACH will be submitted soon for Fed processing. Outgoing ACH in this status can no longer be canceled via the API.	outgoing	No
ach.submitted	The Lead platform has submitted the ACH transfer for Fed processing.	outgoing	Yes
ach.posted	The ACH transfer has successfully completed and has been posted to the receiving bank account. For outbound, if the receiver is at a different bank, the funds may take a few hours to appear.	outgoing incoming	Yes, except if previous status = ach.pending_return
ach.under_review	The ACH transfer has triggered a validation rule that requires further review by the Lead Payment Ops team. Please see best practices on how to avoid this status. We may reach out to you for additional information.	outgoing incoming	Yes for outbound; No for inbound
ach.approved	A successful result of a manual review by Lead. This indicates that the ACH transfer will continue to process.	outgoing incoming	Yes
ach.rejected	An unsuccessful result of a manual review, indicating that Lead Payment Ops has detected an issue with the ACH transfer. Review the data in the rejection hash to determine what to fix and resubmit a corrected ACH transfer if appropriate. This is a terminal status. Please reach out to support via your Slack channel if you have further questions about this decision.	outgoing	Yes
ach.pending_return	The Lead platform has received notice that a previously posted ACH transfer is going to be returned.	incoming	No
ach.returned	A return processed successfully, and the original ACH transaction is now returned.	outgoing incoming	Yes
ach.return_dishonored	A dishonored return processed successfully, and the original ACH transaction is now dishonored.	outgoing incoming	Yes
ach.return_contested	A contested return processed successfully, and the original ACH transaction is now contested.	outgoing incoming	Yes
ach.corrected	Sent if the counterparty has updated any information about their account.	outgoing	Yes

Internal Transfer Events

Event	Description	Webhook Sent
internal_transfer.posted	The internal transfer was completed and money has successfully moved from the `sender_account_number_id` to the `receiver_account_number_id`	Yes
internal_transfer.rejected	The internal transfer was not completed and will not be retried. Please see `rejection.reason` and `rejection.details` for more information.	Yes

Instant Payment Events

Incoming

Event	Description	Webhook Sent
instant_payment.under_review	Lead is manually reviewing the incoming instant payment.	Yes
instant_payment.posted	Lead posted the incoming instant payment to your account.	Yes
instant_payment.rejected	Lead rejected the incoming instant payment.	Yes
instant_payment.return_request_response_needed	You received an incoming return request that requires a response from you.	Yes

Outgoing

Event	Description	Webhook Sent
instant_payment.under_review	Lead is manually reviewing the outgoing instant payment before sending it to the network.	Yes
instant_payment.posted	The outgoing instant payment has been posted to the Lead account.	Yes
instant_payment.rejected	The outgoing instant payment has been rejected by Lead, the counterparty, or the network.	Yes
instant_payment.counterparty_status_updated	The counterparty status of the outgoing instant payment has been updated.	Yes
instant_payment.return_request_status_updated	The status of the outgoing return request has been updated.	Yes

Wire Events

Incoming

Event	Description	Webhook Sent
wire.posted	A wire is received by Lead and funds are successfully posted to the corresponding account’s balance.	Yes
wire.rejected	A wire is received but later rejected by Lead. Lead has returned the funds to the sender. See `rejection` section in the wire object for reasons and dest	Yes

Outgoing

Event	Description	Webhook Sent
wire.created	The wire was created.	No
wire.scheduled	The wire transaction has passed Lead’s internal review and is scheduled to be submitted to the Fedwire network. This is the last stage you can cancel a wire.	Yes
wire.processing	Lead’s system is processing the wire submission. You can not cancel this wire after reaching this stage.	Yes
wire.posted	The wire has been successfully submitted to the counterparty financial institution. `IMAD`value is available in the object.	Yes
wire.under_review	Lead is performing additional review on this wire transaction.	Yes
wire.rejected	Lead has reviewed and rejected this wire transaction.	Yes
wire.cancel_pending	Lead has received the cancel request and we are processing the request.	No
wire.canceled	Lead has successfully canceled the wire and related funds have been returned to your account.	Yes

Account Number Events

Event	Description	Webhook Sent
account_number.created	The Account Number was created.	Yes if created by Lead. Otherwise, no.
account_number.activated	The Account Number was activated.	No; synchronous 200
account_number.deactivated	The Account Number was deactivated.	No; synchronous 200
account_number.canceled	The Account Number was canceled.	No; synchronous 200

Lending Events

Event	Description	Webhook Sent
lending.disbursement.processing	The Disbursement is being processed. You cannot cancel the Disbursement anymore.	Yes
lending.disbursement.succeeded	The Disbursement has succeeded. The funds should have landed in the counterparty’s account.	Yes
lending.disbursement.failed	The Disbursement has failed. The `failure` field on the Disbursement object will provide details on the failure.	Yes
lending.disbursement.ach_correction	Sent if the counterparty’s account details have been corrected by their bank. This is only applicable for ACH.	Yes

Funding Events

Event	Description	Webhook Sent
funding.posted	The funding request was completed and money has successfully moved to the funding account(s) configured for your program.	Yes
funding.rejected	The funding request was not completed and will not be retried.	Yes

Foundations

API Guides

Webhook Authentication

Webhook IP Addresses

Replayed & Missed Events

Pairing Webhooks With Reconciliation

Webhook Format

Event Types

​Webhook Authentication

​Webhook IP Addresses

​Replayed & Missed Events

​Pairing Webhooks With Reconciliation

​Webhook Format

​Event Types

Webhook Authentication

Webhook IP Addresses

Replayed & Missed Events

Pairing Webhooks With Reconciliation

Webhook Format

Event Types