Webhooks

Overview

Webhooks deliver asynchronous notifications from Push to an HTTPS endpoint you control, so your internal state stays accurate without polling — and stays accurate even when an authorization request times out or returns an ambiguous response.

Each event arrives as an HTTP POST carrying a type, a data object, and a timestamp. Push signs the request whenever a signing secret is configured, so you can confirm it came from Push and was not modified in transit. See Security.

Delivery is at-least-once: an event may arrive more than once, and may arrive in any order relative to the authorization response. Your endpoint must verify each event, process it idempotently, and tolerate out-of-order delivery. See Independent ordering and Idempotency.

Webhook types

Type	Cause	Registration
intent.approved	An intent is approved	Authorization
intent.declined	An intent is declined	Authorization
transaction.settled	A transaction settles with the network	Authorization
dispute.created	A completed payment is challenged	Authorization
user.suspended	Push suspends a user	Global

Registration is how you tell Push where to send the event:

• Authorization — supply a webhook URL and secret on each authorize-payment call. Every event about that payment goes there.
• Global — call register-a-webhook once. Every global event goes there until you register again.

Every event carries a type, a data object with the fields below, and a timestamp (ISO 8601).

intent.approved

Triggered when an intent is successfully approved.

Field	Type	Description
id	string	Unique identifier for the intent
tag	string	Your internal transaction identifier (if provided)
direction	string	Either cash_in or cash_out
amount	integer	Amount in cents (e.g. 5000 = $50.00)
status	string	Intent status (approved or pending)
rail	string	Payment rail used (ach or card)
currency	string	Currency code (USD)
type	string	Payment type (secure_debit, card_only_credit, card_only_debit, or apple_pay)
limits_utilization	object	Object containing limit utilization details
limits_utilization.daily_cash_in	string	Daily cash-in limit usage
limits_utilization.daily_cash_out	string	Daily cash-out limit usage
limits_utilization.monthly_cash_in	string	Monthly cash-in limit usage
limits_utilization.monthly_cash_out	string	Monthly cash-out limit usage

intent.declined

Triggered when an intent is declined.

Field	Type	Description
id	string	Unique identifier for the intent
tag	string	Your internal transaction identifier (if provided)
direction	string	Either cash_in or cash_out
amount	integer	Amount in cents (e.g. 5000 = $50.00)
status	string	Intent status (declined)
decline_category	string	Reason for decline – see the full list of decline categories
currency	string	Currency code (USD)
type	string	Payment type (secure_debit, card_only_credit, card_only_debit, or apple_pay)

transaction.settled

Triggered when a transaction reaches its terminal settled status — the funds have settled with the network. For cash_in the funds have been transmitted; for cash_out the network has confirmed the counterparty received the funds. The event is delivered to the same endpoint you configured for the originating payment.

The data object is the settled transaction, including the transfer that settled it.

Field	Type	Description
id	string	Unique identifier for the transaction (prefixed txn_)
amount	integer	Unsigned amount in cents (e.g. 5000 = $50.00). Use direction for the sign
direction	string	Either cash_in or cash_out
currency	string	Currency code (USD)
status	string	Always settled for this event
type	string	What created the transaction: intent, refund, or dispute
source_id	string	The ID of the intent, refund, or dispute that created the transaction
account_id	string	The account the transaction settled against
created_at	string	When the transaction was recorded (ISO 8601)
date	string	The settlement window in which the transaction was submitted
transfer	object	The transfer that settled this transaction
transfer.id	string	Unique identifier for the transfer (prefixed transfer_)
transfer.amount	integer	Net transfer amount in cents
transfer.currency	string	Currency code (USD)
transfer.direction	string	disbursement (net payout to you) or collection (net withdrawal from you)
transfer.date	string	The settlement date of the transfer
transfer.created_at	string	When the transfer was created (ISO 8601)

To reconcile the event against your own records, match source_id (or the tag you set on the originating payment) to your internal record, and use the transfer object to identify the settlement it landed in. See the Ledger guide.

dispute.created

Triggered when a dispute is opened against one of your payments — a card chargeback or an ACH return reversing a completed cash_in. The event is delivered to the same endpoint you configured for the originating payment.

The data object is the dispute. A dispute opens in the created status; its resolution to won or lost is not delivered as a webhook — refetch the dispute or intent to observe the outcome. See Disputes.

Field	Type	Description
id	string	Unique identifier for the dispute (prefixed dispute_)
amount	integer	Disputed amount in cents (e.g. 5000 = $50.00)
currency	string	Currency code (USD)
status	string	Always created for this event
intent_id	string	The intent the dispute was opened against
code	string	The network reason code — an ACH return code (e.g. R01) or a card-network chargeback reason code (e.g. 4853)
type	string	The payment flow type of the associated intent — either card_only or secure_debit; never push
created_at	string	When the dispute was opened (ISO 8601)

To reconcile the event against your own records, match intent_id (or the tag you set on the originating payment) to your internal record. See Disputes.

user.suspended

Triggered when Push suspends a user.

Field	Type	Description
id	string	The suspended user (prefixed user_)
tag	string	Your own identifier for the user, set when you created them. null if you did not set one

Use id as your idempotency key. The envelope timestamp records the delivery attempt and is re-stamped on each retry, so it does not identify the event.

To exercise your handler without waiting for a real suspension, use simulate-a-user-suspension in sandbox. It drives the same delivery path as a production suspension, so the payload and signature are identical.

Suspensions are reviewed by Push Operations and may be lifted. Reinstatement is not delivered as a webhook — Push notifies you directly. You can confirm a user’s current status at any time with get-a-user.

Integration steps

1. Register where events should go. Each registration covers a different set of events, so make the ones you need:

   • To receive intent.approved, intent.declined, transaction.settled, and dispute.created, add webhook_url and webhook_secret to your authorize-payment request. Keep that URL reachable — dispute.created can arrive months after the payment.
   • To receive user.suspended, call register-a-webhook once. Calling it again replaces the registration.

2. Expose an HTTPS endpoint. Accept POST requests at each URL you registered, reachable over HTTPS from the Push IP addresses.

3. Verify each event. Verify the request signature and timestamp before processing, and reject invalid requests with 401 Unauthorized. See Security. Use the secret belonging to the registration the event arrived through.

4. Update your record and acknowledge. Parse the payload (see Webhook types), update the matching record, and return 200 OK. Payment events are keyed on the tag you set when authorizing or on the intent id; user.suspended is keyed on its id. Your integration must tolerate out-of-order and duplicate deliveries — see Independent ordering and Idempotency.

Authorize Payment with Webhook Configuration

curl --request POST \
  --url https://sandbox.pushcash.com/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user_lVpbPL0K1XIiHx0DxipRbD",
  "amount": 2500,
  "currency": "USD",
  "direction": "cash_in",
  "token": "token_mbDRHFi3dxIZEtykHsgUGC",
  "webhook_url": "https://yourapp.com/webhooks/push",
  "webhook_secret": "whsec_32_characters_minimum",
  "tag": "txn_12345"
}
'

intent.approved

{
 "type": "intent.approved",
 "data": {
   "id": "intent_sandbox_mbDRHFi3dxIZEtykHsgUGC",
   "tag": "txn_12345",
   "direction": "cash_in",
   "amount": 5000,
   "status": "approved",
   "rail": "ach",
   "currency": "USD",
   "type": "secure_debit",
   "limits_utilization": {
     "daily_cash_in": "5000.00",
     "daily_cash_out": "0.00",
     "monthly_cash_in": "5000.00",
     "monthly_cash_out": "0.00"
   }
 },
 "timestamp": "2024-01-14T22:31:02.756096Z"
}

Independent ordering

Webhook delivery and authorization responses are independent and may arrive in any order. Your system must handle both scenarios by ensuring that the internal transaction record is committed to the database before the call to the authorization endpoint:

1. Webhook arrives first (before authorization response)
2. Authorization response arrives first (before webhook)

Sequence diagram illustration

Sequence diagram illustrates the two possible scenarios of ordering between webhook delivery and authorization results.

Idempotency

Push provides at-least-once delivery for webhooks. Your application must handle duplicate webhook deliveries gracefully using database transactions to ensure idempotency. In the case of a duplicated webhook delivery from Push either due to an error or timeout from your callback handler, you should discard the request and return a 200 OK.

If Push does not receive a 200 OK response from your webhook endpoint, delivery will be retried with exponential backoff.

Environment	Retry Behavior
Sandbox	Up to 3 attempts
Production	Up to 40 attempts over 3 days, then marked as expired

Security

Webhooks deliver data directly to an endpoint you control over the public internet. Because they are invoked automatically by Push, webhook endpoints must be explicitly secured to prevent unauthorized requests, data tampering, and replay attacks.

Without proper verification, a malicious actor could spoof webhook requests and falsely mark payments as approved or declined in your system.

If your cloud data environment restricts network access from external IPs via a firewall, you may need to allow inbound traffic from Push IP addresses in order to receive webhook requests.

Push webhook source IP addresses

Production 44.238.180.175

Sandbox 34.209.246.44

Signature verification

Push signs a webhook request using an HMAC-SHA256 signature derived from the raw request payload and the signing secret for the registration that event arrived through — the secret from the originating authorize call, or the one from register-a-webhook. Use the event’s type to select which secret to verify against. This allows your application to verify that:

• The request was sent by Push
• The payload has not been modified in transit

Every webhook request must be verified before it is processed.

Both secrets are optional. A registration made without one receives unsigned events — your endpoint cannot authenticate them, and should reject any event it expected to be signed.

Signature format

X-Webhook-Signature: sha256=<hex_encoded_hmac>

Verification steps

1. Extract the signature from the X-Webhook-Signature header
2. Read the raw request body as bytes (before parsing JSON)
3. Compute an HMAC-SHA256 signature using your signing secret and the raw body
4. Compare the computed signature to the received signature using constant-time comparison
5. Reject requests with invalid signatures (401 Unauthorized)

Code examples for signature verification

JavaScript (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(secret, rawBody, signatureHeader) {
  // Parse signature from header
  if (!signatureHeader || !signatureHeader.startsWith('sha256=')) {
    return false;
  }
  
  const receivedSignature = signatureHeader.substring(7); // Remove 'sha256=' prefix
  
  // Compute expected signature
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(rawBody); // rawBody must be Buffer or string
  const expectedSignature = hmac.digest('hex');
  
  // Constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(receivedSignature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

// Express.js example
app.post('/webhooks/push', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const rawBody = req.body; // Raw buffer from express.raw()
  
  if (!verifyWebhookSignature(WEBHOOK_SECRET, rawBody, signature)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Parse JSON after verification
  const payload = JSON.parse(rawBody.toString());
  
  // Verify timestamp (see below)
  // Process webhook...
  
  res.status(200).send('OK');
});

Timestamp Verification

The timestamp field in the webhook payload indicates when the webhook was created. To prevent replay attacks, verify that the timestamp is recent (within 10 minutes).

Verification Steps

1. Parse the timestamp field from the payload (ISO 8601format)
2. Compare with current time
3. Reject requests older than 10 minutes (return401 Unauthorized)

JavaScript (Node.js)

function verifyWebhookTimestamp(timestamp, maxAgeMinutes = 10) {
 const webhookTime = new Date(timestamp);
 const now = new Date();
 const ageMinutes = (now - webhookTime) / 1000 / 60;


 return ageMinutes <= maxAgeMinutes;
}


// In your webhook handler
if (!verifyWebhookTimestamp(payload.timestamp)) {
 return res.status(401).send('Webhook timestamp too old');
}