Webhooks

Receive real-time notifications when events happen in your cred.diy project. Configure webhook endpoints from the Webhooks page in your dashboard.

Webhook Events

credits.issuedCredits were added to a user's account

credits.deductedCredits were removed from a user's account

credits.refundedA credit transaction was reversed

balance.lowUser's balance dropped below threshold

purchase.completedA credit purchase was completed

purchase.failedA credit purchase payment failed

swap.completedA credit swap was successfully executed

referral.completedA referral was successfully processed

subscription.createdA recurring checkout created a subscription

subscription.renewedA paid renewal added credits

subscription.cancel_scheduledA subscription will end after its paid period

subscription.canceledA subscription ended

subscription.payment_failedA renewal payment failed and needs customer action

Payload Envelope

Every delivery includes a unique event id (sent as both id and event_id), the event name as event and type, and a created_at timestamp, alongside the event-specific fields. The same values are mirrored in the X-Cred-Event-Id and X-Cred-Timestamp headers. Use the event id to make your handler idempotent — transient failures (network errors, 5xx, 429) are retried up to three times.

Handling Webhooks

// Set up webhook listener (Express.js example)
const crypto = require('crypto');

app.post('/webhooks/cred', (req, res) => {
  // Verify signature
  const signature = req.headers['x-cred-signature'];
  const expectedSig = crypto
    .createHmac('sha256', 'your_webhook_secret')
    .update(JSON.stringify(req.body))
    .digest('hex');
  
  if (signature !== expectedSig) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  
  switch (req.headers['x-cred-event']) {
    case 'credits.issued':
      console.log('Credits issued:', event);
      break;
    case 'credits.deducted':
      console.log('Credits deducted:', event);
      break;
    case 'purchase.completed':
      console.log('Purchase completed:', event);
      break;
  }
  
  res.status(200).send('OK');
});

Testing Webhooks

Use the Test button next to each webhook endpoint in the dashboard to send a test.ping event. This verifies your endpoint is reachable and responding with a 200 status code before going live.

The test payload includes a X-Cred-Signature header so you can also verify your signature validation logic.

Webhook Security

• Each endpoint has a unique secret generated at creation time
• Verify the X-Cred-Signature header using HMAC-SHA256
• Failed deliveries are visible in the delivery log with full payload/response details
• Always respond with 200 OK to acknowledge receipt

Your first credit is one request away.

Create a project, copy an API key, and issue a credit from your server.

Get an API key Open the dashboard

Webhooks - cred.diy API documentation