Skip to main content

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your Huntrecht account. Instead of polling our API for changes, webhooks push event data to your endpoint as soon as events happen.

Overview​

Huntrecht uses webhooks to notify your application about:

  • Order events - Created, updated, paid, fulfilled, cancelled
  • Payment events - Authorized, captured, refunded, failed
  • Company events - Created, verified, updated
  • Subscription events - Created, renewed, cancelled, payment failed
  • Credit events - Score updated, limit changed

Configuration​

Setting Up Webhook Endpoints​

  1. Go to your Developer Dashboard → Webhooks
  2. Click Add Endpoint
  3. Enter your HTTPS endpoint URL
  4. Select the events you want to subscribe to
  5. Save your configuration

Webhook Payload Structure​

{
  "id": "evt_1234567890",
  "object": "event",
  "type": "order.created",
  "created_at": "2026-04-02T10:30:00Z",
  "data": {
    "object": {
      "id": "ord_abc123",
      "object": "order",
      "company_id": "comp_xyz789",
      "status": "pending",
      "amount": 5000.00,
      "currency": "USD",
      "created_at": "2026-04-02T10:30:00Z"
    }
  }
}

Event Types​

Order Events​

EventDescription
order.createdNew order created
order.updatedOrder details modified
order.paidPayment received
order.fulfilledOrder shipped/delivered
order.cancelledOrder cancelled

Payment Events​

EventDescription
payment.authorizedPayment authorized
payment.capturedPayment captured
payment.refundedRefund processed
payment.failedPayment failed

Company Events​

EventDescription
company.createdNew company registered
company.verifiedCompany KYC verified
company.updatedCompany details updated

Subscription Events​

EventDescription
subscription.createdNew subscription started
subscription.renewedSubscription renewed
subscription.cancelledSubscription cancelled
subscription.payment_failedSubscription payment failed

Security​

Signature Verification​

All webhooks include a signature header for verification:

X-Huntrecht-Signature: t=1648825200,v1=abc123def456

Verify signatures using your webhook secret:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Best Practices​

  1. Use HTTPS - Only accept webhooks over HTTPS
  2. Verify signatures - Always verify webhook signatures
  3. Respond quickly - Return 200 OK within 5 seconds
  4. Handle retries - Webhooks retry up to 5 times with exponential backoff
  5. Idempotency - Handle duplicate events using the event ID

Testing Webhooks​

Local Development​

Use ngrok or similar tools to test webhooks locally:

ngrok http 3000

Then configure the ngrok URL in your webhook settings.

Webhook Testing Endpoint​

Test webhook reception:

curl -X POST https://api.huntrecht.com/v1/webhooks/test \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://your-endpoint.com/webhook",
    "event": "order.created"
  }'

Retry Policy​

If your endpoint returns a non-2xx status code:

AttemptDelay
1Immediate
25 seconds
325 seconds
42 minutes
510 minutes

After 5 failed attempts, the webhook is marked as failed and you must manually retry from the dashboard.

Debugging​

View Webhook Logs​

Access webhook delivery logs in your dashboard:

  1. Go to Developer Dashboard → Webhooks
  2. Select your endpoint
  3. View Delivery History

Common Issues​

IssueSolution
404 Not FoundCheck endpoint URL
500 Server ErrorFix your server code
TimeoutRespond faster, process asynchronously
Invalid signatureCheck webhook secret

Rate Limits​

  • Standard Plan: 10,000 webhooks/day
  • Pro Plan: 100,000 webhooks/day
  • Enterprise: Custom limits

Next Steps​