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
Delete webhook endpoint
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:
- 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")
). - Extract the payload from the JWT.
- Extract the SHA256 signature from the JWT payload
request_body_sha256
field. - Compute the SHA256 signature of the webhook payload.
- 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.
More details about identifiers
and details
for each event can be found in the detailed documentation for each event type/code below.
Webhook payload example
Webhook event types
At a high level, Pier events fall into three types as shown:
In addition to an event type, each event has a more detailed code as summarized in the table below. More detailed descriptions of each event code and the data returned are included in the following section.
Webhook codes
The following webhook codes provide more detail about the nature of the event:
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
Certain event types also include identifiers for relevant Pier entities when appropriate: