docs.cresoracommerce.com/guides/webhooks

Webhooks

Audience:DeveloperEst. time:45 minLast updated:May 2026API:v1Phase:MVP 0

Webhooks are the authoritative source for payment lifecycle state changes. Build your receiver before going live.

Overview

Cresora sends webhook events as signed HTTP POST requests to a URL you register in the Partner Portal. Events represent state transitions — not polling responses. Treat them as the truth.

Register a webhook endpoint

ℹNote

Register your endpoint URL in the Partner Portal under API Settings → Webhooks. Cresora will send a webhook.test event on registration.

Navigate to Partner Portal → API Settings → Webhooks
Click Add endpoint
Enter your HTTPS endpoint URL
Select event categories to subscribe to
Copy the signing secret — you will need it for signature verification

Signature verification

⚠Warning

Always verify the webhook signature before processing. Unverified events must be rejected.

1const crypto = require('crypto');
2 
3function verifyWebhookSignature(payload, signature, secret) {
4  const hmac = crypto.createHmac('sha256', secret);
5  hmac.update(payload, 'utf8');
6  const computed = 'sha256=' + hmac.digest('hex');
7 
8  "color:#4A5568">// Use timingSafeEqual to prevent timing attacks
9  return crypto.timingSafeEqual(
10    Buffer.from(computed),
11    Buffer.from(signature)
12  );
13}
14 
15"color:#4A5568">// In your handler:
16const sig = req.headers['cresora-signature'];
17const isValid = verifyWebhookSignature(
18  req.rawBody, sig, process.env.CRESORA_WEBHOOK_SECRET
19);
20if (!isValid) return res.status(401).send('Invalid signature');

Event types

Event	Description	Trigger
payment.authorized	Auth hold placed	Auth-only payment created
payment.captured	Payment settled	Capture executed
payment.failed	Payment declined	Hard or soft decline
payment.refunded	Refund issued	Full or partial refund
payment.voided	Auth cancelled	Void executed before capture
ach.returned	ACH return received	NACHA return code issued
recurring.payment.succeeded	Plan payment collected	Scheduled plan charge
recurring.payment.failed	Plan payment failed	Retry or failure on schedule
merchant.status_changed	Merchant status transition	Any lifecycle state change
chargeback.received	Chargeback filed	Dispute opened

Retry behavior

⚠Warning

Cresora retries failed deliveries up to 5 times with exponential backoff: 1 min → 5 min → 30 min → 2 hr → 8 hr. Build idempotent receivers — your handler may receive the same event more than once.

💡Tip

Return a 2xx status within 30 seconds. For long processing, acknowledge receipt immediately and process asynchronously.

Local testing with ngrok

1"color:#4A5568"># Install ngrok and expose your local server
2ngrok http 3000
3 
4"color:#4A5568"># Update your webhook URL in the Partner Portal to:
5"color:#4A5568"># https://abc123.ngrok.io/webhooks/cresora
6 
7"color:#4A5568"># Trigger a test event from the Partner Portal
8"color:#4A5568"># or use the test PANs in the sandbox

Common errors

Error	Cause
signature_mismatch	Wrong signing secret or tampered payload
endpoint_timeout	Receiver did not return 2xx within 30s
unsubscribed_event	Event type not enabled for this endpoint

See also: Payments API, Transaction Types.