Skip to main content
Webhooks allow your application to receive real-time notifications when events happen in your Credibill account.

​
Overview

Credibill uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a customer’s bank confirms a payment, a customer disputes a charge, or a recurring payment succeeds.

​
Configuring Webhooks

  1. Go to the Webhooks section in your Dashboard.
  2. Click Add Endpoint.
  3. Enter the URL of your server endpoint (e.g., https://api.myapp.com/webhooks/credibill).
  4. Select the events you want to listen to.

​
Event Structure

Every webhook event payload has a consistent structure. 
{
  "id": "evt_123456",
  "object": "event",
  "type": "invoice.paid",
  "created": 1678900000,
  "data": {
    "object": {
      "id": "in_123456",
      "object": "invoice",
      "amount_due": 1000,
      "status": "paid",
      // ... resource data
    }
  }
}

​
Verifying Signatures

Credibill signs the webhook events it sends to your endpoints by including a signature in each event’s X-Credibill-Signature header. This allows you to verify that the events were sent by Credibill, not by a third party.

​
Node.js Example

const webhookSecret = 'whsec_...';

app.post('/webhook', express.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['x-credibill-signature'];

  let event;

  try {
    event = credibill.webhooks.constructEvent(request.body, sig, webhookSecret);
  } catch (err) {
    response.status(400).send(`Webhook Error: ${err.message}`);
    return;
  }

  // Handle the event
  switch (event.type) {
    case 'invoice.paid':
      const invoice = event.data.object;
      fulfillOrder(invoice);
      break;
    default:
      console.log(`Unhandled event type ${event.type}`);
  }

  response.send();
});
We recommend using the official SDKs to verify signatures as they handle the cryptographic complexity for you.