API docs · 12 of 14

Webhooks

Add your webhook address (it must start with https://) under Business → Developers. You get a signing secret starting with para_whsec_, shown once. When a transaction finishes, we POST this to your address:

Webhook body

{
  "event": "collection.succeeded",
  "data": { "reference": "PRN-8F3K2Q91", "status": "success", ... }
}

data is the full transaction object. Events:

  • collection.succeeded and collection.failed
  • payout.succeeded and payout.failed

Check the signature

Every delivery has this header:

Paranthropus-Signature: t=1763544600,v1=5f2b9c...

t is the time we sent it (Unix seconds). v1 is the hex HMAC-SHA256 of <t>.<raw body>, using your signing secret. Compute it yourself, compare in constant time, and reject old timestamps:

// npm install paranthropus express
import express from 'express';
import { Paranthropus, WebhookSignatureError } from 'paranthropus';

const app = express();
const paranthropus = new Paranthropus(process.env.PARANTHROPUS_SECRET_KEY);
const SECRET = process.env.PARANTHROPUS_WEBHOOK_SECRET; // para_whsec_...

// Read the raw body: the signature covers the exact bytes we sent.
app.post('/paranthropus/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    // Checks the signature and the timestamp (5 minutes), then parses the JSON.
    event = paranthropus.webhooks.verify(req.body, req.get('Paranthropus-Signature'), SECRET);
  } catch (error) {
    if (error instanceof WebhookSignatureError) return res.status(400).send('bad signature');
    throw error;
  }

  // event.event is e.g. "collection.succeeded"; event.data is the transaction.
  // Mark your order as paid here, using event.data.reference.
  res.sendStatus(200);
});

Retries

Reply with any 2xx status within 10 seconds. Otherwise we try again after 1, 2, 4, 8 … minutes, up to 10 tries. You can see every delivery in your dashboard. The same event can arrive more than once, so use data.reference to make sure you only fulfil an order once.