Webhooks

You can configure a single webhook URL to be notified about events from Pier. All events go to the same URL and are distinguished by an event type and code. If you configure the webhook multiple times, the URL will be overwritten and all events will only be delivered to the most recently configured endpoint URL. In addition, deleting the webhook URL will clear it and no events will be delivered, even if the webhook was configured multiple times.

Setup webhook endpoint

See Configuration endpoints in the API reference.

Delete webhook endpoint

See Configuration endpoints in the API reference.

Webhook Authentication (optional, recommended)

Webhooks include a JWT in the pier-webhook-verification header. The JWT payload contains a sha256 signature for the webhook body in the request_body_sha256 field.

To ensure the payload is sourced from Pier:

1. The JWT should be verified using a library for your stack and the Pier public key (see /configuration/webhook-verification). You should replace \n with newlines in the public key before using it (e.g. .replace(/\\n/g, "\n")).
2. Extract the payload from the JWT.
3. Extract the SHA256 signature from the JWT payload request_body_sha256 field.
4. Compute the SHA256 signature of the webhook payload.
5. Ensure that the computed SHA256 and the SHA256 from the JWT match.

Take care not to process the webhook body prior to computing the signature, otherwise you may get a false negative when comparing signatures.

Webhook Object

• type: High-level webhook event type.
• code: Detailed event type.
• env: The Pier environment from which the event was sent (see above).
• url: The url the webhook was sent to.
• timestamp: The time at which the event occurred.
• identifiers: Event-specific identity of the object acted upon in the event.
• details: Event-specific supplemental details about the event.

Generic webhook object example

{
  "type": "example",
  "code": "example_code",
  "env": "sandbox",
  "url": "https://example.com/webhook",
  "timestamp": "2024-10-15T22:00:28.785Z",
  "identifiers": {
    "object_id": "obj_db2f7ce6eba24268a04633e4c560ba44"
  },
  "details": "Additional details about the event"
}

Webhook event types

Webhook codes

• transaction_succeeded
• transaction_failed
• transaction_initiated
• statement_ready
• autopay_scheduled
• payment_due
• payment_late_5_days
• payment_late_10_days
• payment_late_15_days
• payment_late_30_days
• payment_late_45_days
• kyc_approved
• kyc_declined

Identifiers

Detailed webhook examples

Disbursements

Disbursements (and payments) have three events in their lifecycle that trigger webhooks:

• transaction_initiated — indicates that the disbursement has been sent to the ACH network
• transaction_succeeded — indicates that the disbursement has successfully settled
• transaction_failed — indicates that the disbursement has failed, and likely has a return code

{
  "type": "disbursement",
  "code": "transaction_initiated",
  "env": "sandbox",
  "url": "https://example.com/webhook",
  "timestamp": "2024-10-15T21:39:27.051Z",
  "identifiers": {
    "disbursement_id": "dsb_0d22b88519554e8b8df69436f14180d4",
    "facility_id": "fac_207b5820591743fab5994f5b5b2b475e"
  }
}

Payments

Payments have the same events as disbursements (transaction_initiated, transaction_succeeded, transaction_failed). In addition, payments also have autopay and past due events:

• autopay_scheduled — an autopay has been scheduled for the next payment due
• payment_due — a payment is due
• payment_late_5_days through payment_late_45_days — payment is late by the specified number of days

Statements

{
  "type": "statement",
  "code": "statement_ready",
  "env": "sandbox",
  "url": "https://example.com/webhook",
  "timestamp": "2024-10-15T21:39:27.051Z",
  "identifiers": {
    "statement_id": "stmt_0d22b88519554e8b8df69436f14180d4",
    "facility_id": "fac_207b5820591743fab5994f5b5b2b475e"
  }
}

KYC Inquiries

{
  "type": "kyc_inquiry_result",
  "code": "kyc_approved",
  "env": "sandbox",
  "url": "https://example.com/webhook",
  "timestamp": "2024-10-15T21:39:27.051Z",
  "identifiers": {
    "consumer_id": "bor_0ec20e551975485ca49701bb622c6edf"
  }
}

See the KYC Guide for more information.

Webhook retries

If the webhook endpoint does not respond with a 2xx status code, Pier will retry sending the webhook up to 5 times with an exponential backoff. The first retry will be around 10 seconds later, the second after around 2 minutes, the third after around 15–20 minutes, the fourth after 2–3 hours, and the fifth after approximately 1 day. If the webhook still fails after 5 retries, it will be marked as failed and no further retries will be attempted.