Outgoing webhooks

Outgoing webhooks send HTTP POST requests to your server when specific events occur in your Partnero program.

How It Works

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Event     │     │  Partnero   │     │ Your Server │
│   Occurs    │────▶│  Webhook    │────▶│  Endpoint   │
│             │     │  System     │     │             │
└─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    POST /your-webhook
                    {event, url, webhook_key, created_at, data}

Setting Up Outgoing Webhooks

Create your endpoint

Create an HTTPS endpoint on your server to receive webhook events:

// Express.js example
app.post('/webhooks/partnero', (req, res) => {
  const { event, data } = req.body;
  
  // Process the event
  console.log(`Received ${event} event`);
  
  // Respond quickly with 200
  res.status(200).send('OK');
  
  // Process asynchronously if needed
  processWebhookAsync(event, data);
});

To verify signatures (next step) you need the raw, unparsed request body. Make sure your framework gives you access to it — see the verified handler below.

Go to Program Settings → Webhooks
Click Add Webhook
Enter your endpoint URL
Select which events to receive
Save and copy the signing secret

Verify signatures

Every webhook request includes a signature in the Signature header. It is an HMAC-SHA256 hash of the raw request body, keyed with your webhook’s signing secret (the signature value shown when you created the webhook, also returned by the Webhooks API).

You must hash the raw request body bytes exactly as received — not a re-serialized version. Partnero signs the JSON produced by PHP’s json_encode, which escapes forward slashes (https:\/\/...) and non-ASCII characters. Re-stringifying the parsed body (e.g. JSON.stringify(req.body)) produces different bytes and the signature will never match.

const crypto = require('crypto');

// IMPORTANT: capture the raw body, do NOT use express.json() on this route
app.post(
  '/webhooks/partnero',
  express.raw({ type: '*/*' }),
  (req, res) => {
    const received = req.get('Signature'); // header name is "Signature"
    const expected = crypto
      .createHmac('sha256', WEBHOOK_SECRET) // your webhook's signing secret
      .update(req.body)                     // raw Buffer, exactly as received
      .digest('hex');

    const valid =
      received &&
      received.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

    if (!valid) {
      return res.status(401).send('Invalid signature');
    }

    const payload = JSON.parse(req.body.toString('utf8'));
    // payload = { event, url, webhook_key, created_at, data }

    res.status(200).send('OK');
  }
);

<?php
// PHP example
$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $raw, $webhookSecret);

if (!hash_equals($expected, $_SERVER['HTTP_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit('Invalid signature');
}

$payload = json_decode($raw, true);
// $payload = ['event' => ..., 'url' => ..., 'webhook_key' => ..., 'created_at' => ..., 'data' => [...]]

Available Events

Partner Events

Event	Description
`partner.created`	New partner signs up or is created
`partner.updated`	Partner information is updated
`partner.approved`	Partner application is approved
`partner.rejected`	Partner application is rejected
`partner.archived`	Partner is archived
`partner.deleted`	Partner is deleted

Customer Events

Event	Description
`customer.created`	New customer is created
`customer.updated`	Customer information is updated
`customer.deleted`	Customer is deleted

Transaction Events

Event	Description
`transaction.created`	New transaction is recorded
`transaction.updated`	Transaction is updated
`transaction.deleted`	Transaction is deleted (refund)

Reward Events

Event	Description
`reward.created`	Commission/reward is created
`reward.approved`	Reward is approved for payout
`reward.paid`	Reward is marked as paid

Webhook Payload

All webhooks share the same envelope. The event-specific fields are nested under data:

{
  "event": "partner.created",
  "url": "https://your-server.com/webhooks/partnero",
  "webhook_key": "wh_abc123",
  "created_at": "2025-01-15T10:30:00.000000Z",
  "data": {
    "id": "partner_abc123",
    "email": "[email protected]",
    "name": "John",
    "surname": "Doe",
    "status": "approved",
    "created_at": "2025-01-15T10:30:00.000000Z",
    "metadata": {}
  }
}

Field	Type	Description
`event`	string	The event name (e.g. `transaction.created`)
`url`	string	The destination URL the webhook was sent to
`webhook_key`	string	The key of the webhook subscription that fired
`created_at`	string	ISO 8601 timestamp of when the event was dispatched
`data`	object	Event-specific payload (see below)

Event-Specific Payloads

partner.created

{
  "event": "partner.created",
  "data": {
    "id": "partner_abc123",
    "key": "john-doe",
    "email": "[email protected]",
    "name": "John",
    "surname": "Doe",
    "status": "pending",
    "referral_link": "https://yoursite.com?ref=john-doe",
    "created_at": "2025-01-15T10:30:00.000000Z"
  }
}

transaction.created

{
  "event": "transaction.created",
  "data": {
    "key": "txn_123",
    "amount": 99.99,
    "currency": "USD",
    "action": "sale",
    "customer": {
      "id": "cust_456",
      "email": "[email protected]"
    },
    "partner": {
      "id": "partner_abc123",
      "email": "[email protected]"
    },
    "reward": {
      "amount": 19.99,
      "currency": "USD"
    },
    "created_at": "2025-01-15T14:22:00.000000Z"
  }
}

reward.approved

{
  "event": "reward.approved",
  "data": {
    "id": "reward_789",
    "amount": 19.99,
    "currency": "USD",
    "partner": {
      "id": "partner_abc123",
      "email": "[email protected]"
    },
    "transaction_key": "txn_123",
    "approved_at": "2025-01-20T09:00:00.000000Z"
  }
}

Handling Webhooks

Best Practices

Respond Quickly

Return a 2xx status within 5 seconds. Process data asynchronously.

Implement Idempotency

Handle duplicate deliveries by tracking processed event IDs.

Use HTTPS

Always use HTTPS endpoints in production.

Log Everything

Log all received webhooks for debugging and audit trails.

Handling Retries

Partnero retries failed webhooks with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the webhook is marked as failed. Check your webhook logs in the Partnero dashboard.

app.post('/webhooks/partnero', async (req, res) => {
  const { event, data } = req.body;
  
  // Respond immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  switch (event) {
    case 'partner.created':
      await sendWelcomeEmail(data.email, data.name);
      await addToMailingList(data.email);
      await notifySlack(`New partner: ${data.name} (${data.email})`);
      break;
      
    case 'transaction.created':
      await updateCRM(data);
      await syncToAccounting(data);
      break;
      
    case 'reward.approved':
      await schedulePayoutReminder(data);
      break;
  }
});

Testing Webhooks

Using the Dashboard

Go to Program Settings → Webhooks
Find your webhook and click Test
Select an event type
Click Send Test Webhook

Using ngrok for Local Development

# Start ngrok tunnel
ngrok http 3000

# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/partnero

Troubleshooting

Webhooks not arriving

Verify your endpoint URL is correct and accessible
Check your server logs for incoming requests
Ensure your firewall allows requests from Partnero IPs
Check the webhook logs in your Partnero dashboard

Signature verification failing

Ensure you’re using the correct signing secret
Verify you’re hashing the raw request body
Check for any middleware modifying the request body

Duplicate webhooks received

Implement idempotency using event IDs
Track processed webhooks in your database
Return 200 status quickly to prevent retries

API Reference

For programmatic webhook management, see the Webhooks API.

Getting started

Programs

Tracking integration

No-code solutions

Postbacks

Webhooks

AI & MCP

Outgoing webhooks

How It Works

Setting Up Outgoing Webhooks

Available Events

Partner Events

Customer Events

Transaction Events

Reward Events

Webhook Payload

Event-Specific Payloads

Handling Webhooks

Best Practices

Respond Quickly

Implement Idempotency

Use HTTPS

Log Everything

Handling Retries

Testing Webhooks

Using the Dashboard

Using ngrok for Local Development

Troubleshooting

API Reference

​How It Works

​Setting Up Outgoing Webhooks

​Available Events

​Partner Events

​Customer Events

​Transaction Events

​Reward Events

​Webhook Payload

​Event-Specific Payloads

​Handling Webhooks

​Best Practices

Respond Quickly

Implement Idempotency

Use HTTPS

Log Everything

​Handling Retries

​Example: Processing Partner Signup

​Testing Webhooks

​Using the Dashboard

​Using ngrok for Local Development

​Troubleshooting

​API Reference

How It Works

Setting Up Outgoing Webhooks

Available Events

Partner Events

Customer Events

Transaction Events

Reward Events

Webhook Payload

Event-Specific Payloads

Handling Webhooks

Best Practices

Handling Retries

Example: Processing Partner Signup

Testing Webhooks

Using the Dashboard

Using ngrok for Local Development

Troubleshooting

API Reference