Powered by Arrowhead Advisory Group
Developers

41 event types. 11 families. One schema.

Every payment lifecycle event across every connected processor is published through a single canonical schema: Pen.v1. Your integration logic never needs to know which processor handled the transaction. Subscribe once. Stay subscribed.

41
Event types
11
Semantic families
99.9%
Delivery SLO
HMAC-SHA256
Signed
Delivery semantics

What happens between us emitting an event and you receiving it.

99.9%
Delivery SLO
Measured monthly. We credit your account if we miss it.
24h
Retry window
Exponential backoff starting at 30s. After 24h we mark dead-lettered and alert.
HMAC
Signature
SHA-256 over (timestamp + payload). Verify in your handler.
~ 250ms
Median delivery
From event emission at the connector layer to webhook POST.
// Verify the signature in your webhook handler
const sig = req.headers['penumbra-signature'];
const expected = crypto.createHmac('sha256', process.env.PENUMBRA_WEBHOOK_SECRET)
  .update(req.body).digest('hex');
if (sig !== expected) return res.status(401).end();
// Safe to process — payload is authenticated

Transaction

6 events
Lifecycle of a single charge from creation to terminal state. Carries the original routing decision and the processor response on each event.
transaction.created
A charge request reached Penumbra and a decision_id was assigned. Pre-authorization.
transaction.authorized
The chosen processor authorized the charge. Funds reserved, not yet captured.
transaction.captured
Funds captured. Terminal-positive state for auth+capture flows.
transaction.voided
An authorized but uncaptured charge was voided.
transaction.refunded
A refund was issued against the original charge.
transaction.declined
Processor declined. Penumbra may retry on a backup route if the routing policy allows.

Payout

4 events
Money moving to the merchant's bank or wallet. Covers ACH, Same-Day ACH, FedNow, RTP, and USDC settlement.
payout.scheduled
A payout was queued for the next settlement window.
payout.sent
Payout instruction submitted to the rail.
payout.completed
Funds confirmed at the receiving bank or wallet.
payout.failed
Rail rejected the payout. Reason in payload (insufficient funds, account closed, invalid routing, etc.).

Risk

4 events
Decisions from the risk intelligence layer on merchants or transactions.
risk.scored
Composite risk score assigned. Payload includes contributing signal weights.
risk.flagged
A signal crossed the alert threshold. Reason and severity attached.
risk.approved
A flagged item was reviewed (manually or auto) and approved to proceed.
risk.declined
A flagged item was reviewed and declined.

Chargeback

4 events
Disputes inbound from the card networks. The chargeback engine fires events as the case moves through carrier states.
chargeback.received
A dispute was opened by the issuer. Evidence assembly begins automatically.
chargeback.represented
Rebuttal package submitted to the carrier.
chargeback.won
Carrier ruled in your favor. Funds restored.
chargeback.lost
Carrier ruled for the cardholder. Funds remain debited.

Settlement

2 events
Settlement batches from each processor. Use these to reconcile against processor statements.
settlement.batch_created
A new settlement batch was opened. Empty until transactions get pulled in.
settlement.completed
Settlement closed and funds moved. Payload includes settled amount and batch composition.

Refund

2 events
Refund lifecycle. Distinct from transaction.refunded which fires on the parent transaction.
refund.created
Refund instruction submitted.
refund.processed
Refund completed at the processor and reflected on the cardholder's statement.

Merchant

5 events
Merchant lifecycle from boarding through suspension or churn.
merchant.boarded
KYB approved and the merchant can begin processing.
merchant.updated
Merchant profile or settings changed.
merchant.suspended
Processing suspended (by us, by the PSP, or by you).
merchant.reinstated
A previously suspended merchant is back to processing.
merchant.churned
Merchant terminated. No further transactions accepted on this account.

Compliance

3 events
Violations and resolutions surfaced by the compliance domain.
compliance.violation_detected
A surcharge cap, MCC mismatch, or BSA/AML indicator fired.
compliance.violation_resolved
The violation was addressed (action taken, exception granted, or appealed).
compliance.report_generated
A scheduled compliance report is ready for download.

Webhook

3 events
Webhook plumbing events. Useful for monitoring your own integration health.
webhook.delivered
A previous webhook delivery succeeded (2xx response from your endpoint).
webhook.failed
Delivery failed. Will retry per backoff schedule.
webhook.dead_lettered
24 hours of retries exhausted. We'll stop trying and alert.

Integration

4 events
PSP / rail / connector connectivity state changes.
integration.connected
A new processor or rail was added to your account.
integration.disconnected
Processor / rail removed.
integration.degraded
Performance below threshold (e.g. p99 latency > 250ms over 5 min). Routing may failover.
integration.recovered
Degraded integration back to healthy.

System

4 events
Platform-level events. Subscribe these to your alerting system, not your business logic.
system.alert
Operational alert from Penumbra (e.g. account quota approaching limit).
system.maintenance_scheduled
Planned maintenance window announced in advance.
system.maintenance_completed
Maintenance window finished, all services back to normal.
system.incident
Unplanned incident. Severity level in payload.

Need an event we don't publish yet?

The catalogue is opinionated but extendable. Tell us what you need and we'll often ship it within a release.

Request an event