Webhooks

Lead sends webhooks to notify you about events that happen witin your program. We uses 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 millisecond
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.

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.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. From here, the payment will move to `returned` if successful, or back to `posted` if not (which will not trigger a new ach.posted webhook).	incoming	No
ach.returned	A successful return ACH has been fully processed and the original ACH transfer was returned. This is a terminal status (as, even in the case of a dishonored return, this original payment will not change status).	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

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.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 as successfully canceled the wire and related funds has been returned to your account.	No

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

Webhook Format

Event Types

Foundations

API Guides

​Webhook Authentication

​Webhook IP Addresses

​Replayed & Missed Events

​Webhook Format

​Event Types

Webhook Authentication

Webhook IP Addresses

Replayed & Missed Events

Webhook Format

Event Types