Webhooks deliver real-time notifications about payment events. Prism POSTs a signed JSON payload to your configured endpoint whenever a payment is completed, fails, or settles. Use webhooks to update order status, trigger fulfillment, log transactions, or sync with your backend.
Setup
Create an endpoint
Add an HTTP POST endpoint to your application that accepts JSON payloads.
Register in the Console
Go to Prism Console → Settings → Webhooks
→ Add Endpoint. Enter your URL and select the events you want to
receive. Copy the signing secret
The Console generates a signing secret for your endpoint. Copy it — you’ll
need it to verify webhook signatures.
Example Endpoint
import express from "express";
import crypto from "crypto";
const app = express();
app.use(express.raw({ type: "application/json" }));
const WEBHOOK_SECRET = process.env.PRISM_WEBHOOK_SECRET;
app.post("/webhooks/prism", (req, res) => {
const signature = req.headers["x-prism-signature"] as string;
const payload = req.body.toString();
// Verify signature
const expected = crypto
.createHmac("sha256", WEBHOOK_SECRET)
.update(payload)
.digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send("Invalid signature");
}
const event = JSON.parse(payload);
switch (event.type) {
case "payment.completed":
// Payment verified and settled on-chain
handlePaymentCompleted(event.data);
break;
case "payment.failed":
// Payment verification failed
handlePaymentFailed(event.data);
break;
case "settlement.completed":
// Funds settled to merchant wallet
handleSettlement(event.data);
break;
}
// Respond 200 quickly — process asynchronously if needed
res.status(200).send("OK");
});
Event Types
| Event | Description | Triggered When |
|---|
payment.pending | Payment submitted, awaiting confirmation | After agent submits payment on-chain |
payment.completed | Payment verified and settled | After on-chain confirmation by Spectrum |
payment.failed | Payment verification failed | Invalid transaction, wrong amount, or expired |
settlement.completed | Funds settled to merchant wallet | After Spectrum settlement completes |
{
"id": "evt_abc123def456",
"type": "payment.completed",
"created": "2025-01-15T10:30:00Z",
"data": {
"payment_id": "pay_xyz789ghi012",
"amount": "10000",
"token": "USDC",
"chain": "base",
"from": "0xAgentWallet1234567890abcdef1234567890abcdef",
"to": "0xMerchantWallet1234567890abcdef1234567890ab",
"tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
"endpoint": "/api/premium/data",
"status": "completed"
}
}
| Field | Description |
|---|
id | Unique event identifier |
type | Event type (see table above) |
created | ISO 8601 timestamp |
data.payment_id | Prism payment/charge identifier |
data.amount | Amount in token base units |
data.token | Token symbol (FDUSD, USDC) |
data.chain | Chain where settlement occurred |
data.from | Agent wallet address |
data.to | Merchant wallet address |
data.tx_hash | On-chain transaction hash |
data.endpoint | The merchant endpoint that triggered the charge |
data.status | Payment status |
Signature Verification
All webhooks include an X-Prism-Signature header containing an HMAC-SHA256 signature of the raw request body, using your webhook signing secret as the key.
Always verify signatures before processing events. This prevents spoofed requests from triggering actions in your application.
import crypto from "crypto";
function verifyWebhookSignature(
payload: string,
signature: string,
secret: string
): boolean {
const expected = crypto
.createHmac("sha256", secret)
.update(payload)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
import hmac
import hashlib
def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
Use constant-time comparison (timingSafeEqual / hmac.compare_digest) to
prevent timing attacks. Do not use === or == for signature comparison.
Retry Policy
If your endpoint returns a non-2xx response, times out, or is unreachable, Prism retries delivery with exponential backoff:
| Attempt | Delay After Failure |
|---|
| 1 | Immediate |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 24 hours |
- Respond with 200 as quickly as possible — do heavy processing asynchronously
- Use a queue (SQS, Redis, etc.) for webhook processing in high-volume scenarios
- Implement idempotency using the event
id to handle duplicate deliveries
Testing Webhooks
- Console test button — Send a test event from the Prism Console to verify your endpoint is reachable and responding correctly
- Local development — Use a tunneling tool like ngrok to expose your local endpoint for testing
- Small amount testing — Use production with small amounts to verify your full webhook pipeline end-to-end
