Integrating into Webhooks

Managing Webhooks via Dashboard

HL Hunt supports creating and updating webhooks through the Dashboard with the following options:

• Set URL: Set the URL you'd like HL Hunt to send webhooks to.
• Set Authentication: Choose Basic or Bearer authentication (recommended), or no authentication.
• Filter Events: Subscribe to all events, or choose specific events.
• Update Webhooks: Update existing webhooks (change URL or events).
• Disable Webhooks: Disable webhooks you no longer use.

Viewing Webhooks

To create or update webhooks, navigate to Developers > Webhooks. There, you will see a list of all webhooks you have created.

Creating Webhooks

Click Create Webhook to create a new webhook. You'll set the URL, Authentication Type, and Events you'd like to subscribe to.

Managing Webhooks via API

You can also create and manage webhooks programmatically via the HL Hunt API.

Creating a Webhook

POST /api/v1/webhooks
Authorization: Bearer sk_live_your_api_key

{
  "url": "https://your-server.com/webhooks/hlhunt",
  "events": ["charge.succeeded", "refund.created", "dispute.opened"],
  "description": "Production webhook"
}

The response includes a secret (signing key) that you use to verify incoming webhook payloads:

{
  "id": "we_abc123",
  "object": "webhook_endpoint",
  "url": "https://your-server.com/webhooks/hlhunt",
  "description": "Production webhook",
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "active": true,
  "events": ["charge.succeeded", "refund.created", "dispute.opened"],
  "created": "2026-06-23T00:00:00Z"
}

Listing Webhooks

List every webhook endpoint on your account. The signing secret is only ever returned once at creation, so it is omitted here.

GET /api/v1/webhooks
Authorization: Bearer sk_live_your_api_key

{
  "object": "list",
  "data": [
    {
      "id": "we_abc123",
      "object": "webhook_endpoint",
      "url": "https://your-server.com/webhooks/hlhunt",
      "description": "Production webhook",
      "active": true,
      "events": ["charge.succeeded", "refund.created", "dispute.opened"],
      "created": "2026-06-23T00:00:00Z"
    }
  ],
  "has_more": false
}

Verifying Webhook Signatures

Every webhook event includes a signature header that lets you verify the payload wasn't tampered with and was sent recently.

To validate:

1. Parse the timestamp and sig from the header.
2. Ensure the timestamp is within 5 minutes (protects against replay attacks).
3. Recompute HMAC-SHA256 of timestamp:body using the webhook signing key.
4. Compare signatures using constant-time comparison.

Delivery Attempts and Retries

When a delivery fails, HL Hunt retries up to 5 times using exponential backoff. Any 2xx HTTP status code counts as successful delivery.

After all retries are exhausted, the event will not be resent. Use the API to query resources directly if you suspect missed events.

Test & Live Mode Isolation

Webhook endpoints are mode-scoped. An endpoint created with a live API key (sk_live_) only receives events generated by live transactions. An endpoint created with a test API key (sk_test_) only receives events generated by test transactions. Live events are never delivered to test endpoints, and test events are never delivered to live endpoints.

Every webhook payload includes two fields that identify the mode:

We recommend verifying the livemode field in your webhook handler as defence-in-depth, even though mode isolation is enforced at the delivery layer. This protects against misconfigured endpoints and makes the mode explicit in your application logic.

// Example: verify mode in your webhook handler
const payload = JSON.parse(body)
if (payload.livemode === false) {
  // Test event — log and return 200 without processing real orders
  console.log("Test webhook received:", payload.type)
  return respond(200)
}

// Live event — process normally
processOrder(payload)