SDK Documentation

Official SDKs for Python and Node.js. Install via your package manager and start sending webhooks in seconds.

🐍

Python SDK

Installation

pip install hooksniff

Quick Start

import hooksniff
import os

# Initialize the client
client = hooksniff.Client(api_key=os.environ["HOOKRELAY_KEY"])

# Create an endpoint
endpoint = client.endpoints.create(
    url="https://myapp.com/webhook",
    description="Production webhook"
)
print(f"Endpoint ID: {endpoint.id}")
print(f"Signing Secret: {endpoint.signing_secret}")

# Send a webhook
delivery = client.webhooks.send(
    endpoint_id=endpoint.id,
    event="order.created",
    data={
        "order_id": "12345",
        "total": 99.99,
        "currency": "USD",
    }
)
print(f"Delivery ID: {delivery.id}")
print(f"Status: {delivery.status}")

Verify Signatures

from flask import Flask, request, abort
import hooksniff

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-HookSniff-Signature")
    if not hooksniff.verify_signature(
        payload=request.data,
        signature=signature,
        secret="whsec_your_signing_secret"
    ):
        abort(401)

    event = request.json
    print(f"Received: {event['event']}")
    return "", 200

Error Handling

import hooksniff

try:
    delivery = client.webhooks.send(
        endpoint_id="ep_abc123",
        event="test.event",
        data={"test": True}
    )
except hooksniff.RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except hooksniff.AuthenticationError:
    print("Invalid API key")
except hooksniff.HookSniffError as e:
    print(f"Error: {e.message}")

📦

Node.js SDK

Installation

npm install @hooksniff/sdk

Quick Start

import { HookSniff } from '@hooksniff/sdk';

const hr = new HookSniff({ apiKey: process.env.HOOKRELAY_KEY! });

// Create an endpoint
const endpoint = await hr.endpoints.create({
  url: 'https://myapp.com/webhook',
  description: 'Production webhook',
});
console.log('Endpoint:', endpoint.id);
console.log('Secret:', endpoint.signing_secret);

// Send a webhook
const delivery = await hr.webhooks.send({
  endpointId: endpoint.id,
  event: 'order.created',
  data: {
    order_id: '12345',
    total: 99.99,
    currency: 'USD',
  },
});
console.log('Delivery:', delivery.id, delivery.status);

Verify Signatures

import express from 'express';
import { verifySignature } from '@hooksniff/sdk';
import { useTranslations } from 'next-intl';

const app = express();

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-hooksniff-signature'] as string;

  if (!verifySignature(req.body, signature, 'whsec_your_secret')) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  console.log('Received:', event.event);
  res.status(200).send('OK');
});

TypeScript Support

import type { Endpoint, Delivery, WebhookEvent } from '@hooksniff/sdk';

// Full type safety for all API responses
const endpoints: Endpoint[] = await hr.endpoints.list();
const delivery: Delivery = await hr.webhooks.send({
  endpointId: 'ep_abc123',
  event: 'user.created',
  data: { email: 'user@example.com' } satisfies WebhookEvent,
});

Community SDKs

Community-maintained SDKs are available for other languages. These are not officially supported but are actively maintained.

GoStable

github.com/hooksniff/hooksniff-go

RubyBeta

gem install hooksniff

PHPBeta

composer require hooksniff/hooksniff-php

RustAlpha

cargo add hooksniff