Guide8 min

Set Up Webhooks

Learn how to configure webhook endpoints and handle real-time event notifications. Webhooks allow your application to react to events as they happen in the Hyperscale platform.

How Webhooks Work

Hyperscale sends HTTP POST requests to your endpoint when events occur.

Real-time

Events delivered within seconds of occurring

Reliable

Automatic retries with exponential backoff

Secure

HMAC signatures for payload verification

Register a Webhook

Create a webhook endpoint and specify which events you want to receive.

typescript

1import { Hyperscale } from '@hyperscale/sdk';
2
3const hyperscale = new Hyperscale({
4  apiKey: process.env.HYPERSCALE_API_KEY,
5});
6
7// Register a webhook endpoint
8const webhook = await hyperscale.webhooks.create({
9  url: 'https://api.yourapp.com/webhooks/hyperscale',
10  events: [
11    'payment.completed',
12    'payment.failed',
13    'card.issued',
14    'account.updated',
15  ],
16  secret: process.env.WEBHOOK_SECRET,
17});
18
19console.log('Webhook ID:', webhook.id);
20console.log('Signing key:', webhook.signingKey);

Event Types

Subscribe to specific events relevant to your integration.

Payments

payment.initiatedPayment has been created

payment.completedPayment successfully delivered

payment.failedPayment failed to process

payment.cancelledPayment was cancelled

Cards

card.issuedNew card was issued

card.activatedCard is ready for use

card.frozenCard was temporarily frozen

card.blockedCard was permanently blocked

Accounts

account.createdNew account opened

account.updatedAccount details changed

account.closedAccount was closed

balance.updatedAccount balance changed

Verify Signatures

Always verify the webhook signature to ensure requests come from Hyperscale.

verify-signature.ts

typescript

1import crypto from 'crypto';
2
3function verifyWebhookSignature(
4  payload: string,
5  signature: string,
6  secret: string
7): boolean {
8  const timestamp = signature.split(',')[0].split('=')[1];
9  const sig = signature.split(',')[1].split('=')[1];
10
11  const signedPayload = timestamp + '.' + payload;
12  const expectedSig = crypto
13    .createHmac('sha256', secret)
14    .update(signedPayload)
15    .digest('hex');
16
17  return crypto.timingSafeEqual(
18    Buffer.from(sig),
19    Buffer.from(expectedSig)
20  );
21}

Security: Never skip signature verification. Attackers could send fake webhooks to your endpoint.

Handle Events

Process webhook events in your application. Always return a 2xx response quickly.

webhook-handler.ts

typescript

1import express from 'express';
2
3const app = express();
4
5app.post('/webhooks/hyperscale', express.raw({ type: 'application/json' }), (req, res) => {
6  const signature = req.headers['x-hyperscale-signature'] as string;
7  const payload = req.body.toString();
8
9  // Verify signature
10  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
11    return res.status(401).send('Invalid signature');
12  }
13
14  const event = JSON.parse(payload);
15
16  switch (event.type) {
17    case 'payment.completed':
18      console.log('Payment completed:', event.data.id);
19      // Update your database, notify user, etc.
20      break;
21
22    case 'payment.failed':
23      console.log('Payment failed:', event.data.id);
24      // Handle failure, retry logic, etc.
25      break;
26
27    case 'card.issued':
28      console.log('Card issued:', event.data.id);
29      // Notify user, update UI, etc.
30      break;
31
32    default:
33      console.log('Unhandled event:', event.type);
34  }
35
36  res.status(200).send('OK');
37});

Retry Policy

If your endpoint fails to respond, we retry with exponential backoff.

Attempt	Delay	Note
1st	`Immediate`	Sent instantly
2nd	`5 minutes`	If first fails
3rd	`30 minutes`	Exponential backoff
4th	`2 hours`	Extended retry
5th	`24 hours`	Final attempt

Best Practices

Return 2xx within 5 seconds, process async if needed
Handle duplicate events (use idempotency keys)
Store events before processing for recovery
Monitor webhook failures and set up alerts
Use a queue for high-volume event processing

Related Guides

Process Payments

Issue a Card

Create a webhook endpoint and specify which events you want to receive.

typescript

1import { Hyperscale } from '@hyperscale/sdk';
2
3const hyperscale = new Hyperscale({
4  apiKey: process.env.HYPERSCALE_API_KEY,
5});
6
7// Register a webhook endpoint
8const webhook = await hyperscale.webhooks.create({
9  url: 'https://api.yourapp.com/webhooks/hyperscale',
10  events: [
11    'payment.completed',
12    'payment.failed',
13    'card.issued',
14    'account.updated',
15  ],
16  secret: process.env.WEBHOOK_SECRET,
17});
18
19console.log('Webhook ID:', webhook.id);
20console.log('Signing key:', webhook.signingKey);

Event Types

Subscribe to specific events relevant to your integration.

Payments

payment.initiatedPayment has been created

payment.completedPayment successfully delivered

payment.failedPayment failed to process

payment.cancelledPayment was cancelled

Cards

card.issuedNew card was issued

card.activatedCard is ready for use

card.frozenCard was temporarily frozen

card.blockedCard was permanently blocked

Accounts

account.createdNew account opened

account.updatedAccount details changed

account.closedAccount was closed

balance.updatedAccount balance changed

Verify Signatures

Always verify the webhook signature to ensure requests come from Hyperscale.

verify-signature.ts

typescript

1import crypto from 'crypto';
2
3function verifyWebhookSignature(
4  payload: string,
5  signature: string,
6  secret: string
7): boolean {
8  const timestamp = signature.split(',')[0].split('=')[1];
9  const sig = signature.split(',')[1].split('=')[1];
10
11  const signedPayload = timestamp + '.' + payload;
12  const expectedSig = crypto
13    .createHmac('sha256', secret)
14    .update(signedPayload)
15    .digest('hex');
16
17  return crypto.timingSafeEqual(
18    Buffer.from(sig),
19    Buffer.from(expectedSig)
20  );
21}

Security: Never skip signature verification. Attackers could send fake webhooks to your endpoint.

Handle Events

Process webhook events in your application. Always return a 2xx response quickly.

webhook-handler.ts

typescript

1import express from 'express';
2
3const app = express();
4
5app.post('/webhooks/hyperscale', express.raw({ type: 'application/json' }), (req, res) => {
6  const signature = req.headers['x-hyperscale-signature'] as string;
7  const payload = req.body.toString();
8
9  // Verify signature
10  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
11    return res.status(401).send('Invalid signature');
12  }
13
14  const event = JSON.parse(payload);
15
16  switch (event.type) {
17    case 'payment.completed':
18      console.log('Payment completed:', event.data.id);
19      // Update your database, notify user, etc.
20      break;
21
22    case 'payment.failed':
23      console.log('Payment failed:', event.data.id);
24      // Handle failure, retry logic, etc.
25      break;
26
27    case 'card.issued':
28      console.log('Card issued:', event.data.id);
29      // Notify user, update UI, etc.
30      break;
31
32    default:
33      console.log('Unhandled event:', event.type);
34  }
35
36  res.status(200).send('OK');
37});

Attempt

Delay

Note

1st

Immediate

Sent instantly

2nd

5 minutes

If first fails

3rd

30 minutes

Exponential backoff

4th

2 hours

Extended retry

5th

24 hours

Final attempt