Webhooks

Webhooks

Real-time notifications when payment events occur.

Register an HTTPS endpoint, and Harpoon will POST signed JSON when an event happens. Failed deliveries retry with exponential backoff.

Create an endpoint

Dashboard

Settings → Webhooks → Add Endpoint. Paste your URL, pick events, save. The signing secret is shown once.

API

Bash 
POST /v1/webhooks
Authorization: Bearer hpn_live_sk_xxxxxxxxxxxxx
Content-Type: application/json

{
  "url": "https://your-server.com/webhooks/harpoon",
  "events": ["transaction.completed", "transaction.failed", "transaction.expired"],
  "description": "Production webhook"
}

Scope: webhooks:manage

JSON 
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://your-server.com/webhooks/harpoon",
    "events": ["transaction.completed", "transaction.failed", "transaction.expired"],
    "secret": "whsec_xxxxxxxxxxxxxxxxxxxxx",
    "is_active": true,
    "created_at": "2026-04-29T12:00:00Z"
  },
  "message": "Webhook endpoint created. Save the secret now - it won't be shown again."
}

The secret is only returned at creation. Reveal it later via the dashboard with your password — see management.

In this section

Events

All event types and payloads.

Verifying signatures

HMAC-SHA256 with examples.

Handling deliveries

Idempotency and a sample handler.

Retries & dead letters

Schedule and manual replay.

Management

List, update, delete, test, reveal secret.