Webhooks

Listen for real-time events from CryptoPay to trigger actions in your backend systems.

Last updated: June 22, 2023

Overview

Webhooks allow your application to receive real-time notifications about events that happen in your CryptoPay account. When an event occurs—like a successful payment or a failed charge—CryptoPay sends an HTTP POST request to a URL that you configure.

Real-time Updates

Receive instant notifications when important events occur in your account.

Asynchronous Processing

Handle long-running tasks like order fulfillment without keeping the user waiting.

Reliable Delivery

Automatic retries ensure you never miss an event, even if your server is temporarily down.

Setting up Webhooks

Follow these steps to start receiving webhook events:

Create an Endpoint

Set up an HTTP endpoint on your server that can accept POST requests. This URL must be publicly accessible.

Register Webhook URL

In the CryptoPay Dashboard, go to Developers → Webhooks and click 'Add Endpoint'. Enter your URL and select the events you want to listen to.

Handle Requests

Your endpoint should parse the JSON body of the request to get the event details. Always return a 200 OK status to acknowledge receipt.

Verify Signatures

Verify the webhook signature to ensure the request actually came from CryptoPay and hasn't been tampered with.

Event Types

CryptoPay sends various events depending on what happens in your account:

Event Name	Description
`payment_intent.created`	Occurs when a new payment intent is created.
`payment_intent.succeeded`	Occurs when a payment has been successfully completed.
`payment_intent.processing`	Occurs when a payment is being processed by the blockchain.
`payment_intent.failed`	Occurs when a payment attempt fails.
`payment_intent.amount_capturable_updated`	Occurs when a payment amount changes.
`charge.refunded`	Occurs when a charge is refunded.

Security & Verification

It is critical to verify that requests to your webhook endpoint are actually from CryptoPay. We sign every webhook request so you can verify its authenticity.

Security Warning

Never trust the payload of a webhook without verifying the signature first. Attackers could send fake webhook events to your endpoint.

Verification Example (Node.js)

const express = require('express');
const app = express();
const CryptoPay = require('CryptoPay');

// This is your CryptoPay CLI webhook secret for testing your endpoint locally.
const endpointSecret = "whsec_...";

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

  try {
    // Verify the webhook signature
    event = CryptoPay.webhooks.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    console.log(`Webhook Error: ${err.message}`);
    response.status(400).send(`Webhook Error: ${err.message}`);
    return;
  }

  // Handle the event
  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      console.log('PaymentSucceeded:', paymentIntent.id);
      // Fulfill the order...
      break;
    default:
      console.log(`Unhandled event type ${event.type}`);
  }

  // Return a 200 response to acknowledge receipt of the event
  response.send();
});

app.listen(4242, () => console.log('Running on port 4242'));