Webhooks

Receive real-time event notifications. Payroo signs every delivery with HMAC-SHA256.

Signature Verification

Every delivery includes a Payroo-Signature header:t=TIMESTAMP,v1=HMAC_HEX. Compute HMAC-SHA256(secret, "TIMESTAMP.PAYLOAD") and compare. Retry schedule: 1s → 5s → 30s → 5m → 30m.

GET/v1/webhooks

List webhook endpoints

Returns all webhook endpoints for your merchant account.

Required scope:webhooks:manage

Response

{
  "data": [
    {
      "id": "wh_01HXYZ",
      "url": "https://example.com/webhooks",
      "events": [
        "payment.succeeded"
      ],
      "is_active": true,
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

POST/v1/webhooks

Create webhook endpoint

Creates a new webhook endpoint. The signing secret is returned only once — store it securely.

Required scope:webhooks:manage

Request Body

Parameter	Type	Required	Description
url	string	Yes	HTTPS URL to receive events
events	array	Yes	Event types to subscribe to

Response

{
  "id": "wh_01HXYZ",
  "url": "https://example.com/webhooks",
  "events": [
    "payment.succeeded",
    "payout.succeeded"
  ],
  "is_active": true,
  "secret": "whsec_abc123...",
  "created_at": "2024-01-01T00:00:00.000Z"
}

DELETE/v1/webhooks/:id

Delete webhook endpoint

Permanently deletes a webhook endpoint.

Required scope:webhooks:manage

Response

{}

POST/v1/webhooks/:id/test

Test webhook endpoint

Sends a test payment.succeeded event to the endpoint and returns the delivery result.

Required scope:webhooks:manage

Response

{
  "id": "del_01HXYZ",
  "status": "DELIVERED",
  "response_status": 200,
  "attempts": 1
}