DOCUMENTATION

INTRODUCTION

PatternHooks is enterprise-grade webhook infrastructure that handles sending, receiving, and managing webhooks at any scale. This documentation will help you integrate webhooks into your application quickly and reliably.

ON THIS PAGE

What is PatternHooks?
Core Concepts
How It Works
Quick Start
Authentication
Error Handling
Next Steps

🚀

QUICK START

Send your first webhook in 5 minutes

📡

API REFERENCE

Complete REST API documentation

📦

SDKS

Official libraries for all languages

WHAT IS PATTERNHOOKS?

PatternHooks provides the infrastructure layer for webhooks so you can focus on your core product. Instead of building and maintaining webhook delivery systems, retry logic, signature verification, and monitoring dashboards yourself, PatternHooks handles all of this for you.

Whether you're building a SaaS platform that needs to notify customers of events, or integrating with third-party services that send webhooks, PatternHooks ensures reliable, secure, and observable webhook delivery.

Key Benefits

Guaranteed Delivery: Automatic retries with exponential backoff ensure your webhooks are delivered even when endpoints are temporarily unavailable.
Security Built-in: Every webhook is cryptographically signed using HMAC-SHA256, allowing recipients to verify authenticity.
Full Observability: Real-time dashboards show delivery status, latency metrics, and failure rates across all your webhooks.
Developer Experience: SDKs for every major language, comprehensive documentation, and a CLI for local development.
Scale Effortlessly: Handle millions of webhooks per day without infrastructure changes. We scale automatically.

CORE CONCEPTS

Understanding these four core concepts will help you get the most out of PatternHooks:

📱 APPLICATIONS

Applications are logical containers for webhooks, typically representing one of your customers or a distinct integration. Each application has its own set of endpoints and can subscribe to different event types. Think of an application as "Acme Corp's webhook configuration."

🎯 ENDPOINTS

Endpoints are the URLs where webhooks are delivered. Each application can have multiple endpoints (e.g., production and staging). Endpoints can filter which event types they receive and have their own signing secrets for verification.

⚡ MESSAGES

Messages are the actual webhook payloads you send. Each message has an event type and a JSON payload. When you send a message, PatternHooks delivers it to all endpoints subscribed to that event type within the application.

📋 EVENT TYPES

Event types categorize your webhooks (e.g., order.created, user.deleted). Endpoints subscribe to specific event types, so they only receive relevant webhooks. This reduces noise and processing overhead.

HOW IT WORKS

Here's the typical flow when you send a webhook through PatternHooks:

WEBHOOK DELIVERY FLOW

Your App

→

PatternHooks API

→

Queue & Sign

→

Deliver to Endpoints

→

Retry if Failed

You send a message to our API with an event type and payload
We identify all endpoints subscribed to that event type within the application
We sign the payload with each endpoint's unique signing secret
We deliver the webhook to each endpoint with appropriate headers
If delivery fails, we automatically retry with exponential backoff
You can monitor delivery status in real-time via dashboard or API

QUICK START

Get up and running in minutes. Here's how to send your first webhook:

1. Install the SDK

Terminal

# Node.js
npm install @patternhooks/sdk

# Python
pip install patternhooks

# Go
go get github.com/patternhooks/patternhooks-go

# Ruby
gem install patternhooks

2. Initialize the Client

JavaScript

import { PatternHooks } from '@patternhooks/sdk';

// Initialize with your API key (find it in Dashboard → Settings → API Keys)
const ph = new PatternHooks('sk_live_your_api_key_here');

3. Create an Application

Applications typically represent one of your customers:

JavaScript

const app = await ph.application.create({
  name: 'Acme Corporation',
  uid: 'customer_12345',  // Your internal customer ID
  metadata: {
    plan: 'enterprise',
    region: 'us-east'
  }
});

console.log('Created application:', app.id);
// Output: Created application: app_2X8BfDj3K4mN

4. Add an Endpoint

This is where webhooks will be delivered:

JavaScript

const endpoint = await ph.endpoint.create(app.id, {
  url: 'https://acme.com/webhooks/patternhooks',
  description: 'Production webhook endpoint',
  filterTypes: ['order.created', 'order.updated', 'payment.completed'],
  rateLimit: 100,  // Max 100 requests per second
  metadata: {
    environment: 'production'
  }
});

console.log('Endpoint created with signing secret:', endpoint.secret);
// Output: Endpoint created with signing secret: whsec_abc123...

5. Send Your First Webhook

JavaScript

const message = await ph.message.create(app.id, {
  eventType: 'order.created',
  eventId: 'evt_unique_id_for_idempotency',  // Optional
  payload: {
    orderId: 'ord_abc123',
    customerId: 'cus_xyz789',
    amount: 9900,
    currency: 'usd',
    items: [
      { sku: 'WIDGET-001', quantity: 2, price: 4950 }
    ],
    createdAt: new Date().toISOString()
  }
});

console.log('Message sent:', message.id);
// Output: Message sent: msg_7K9mNpQrSt

💡 Pro Tip

Use eventId for idempotency. If you accidentally send the same event twice with the same eventId, we'll only deliver it once.

AUTHENTICATION

All API requests require authentication using a Bearer token in the Authorization header:

HTTP

GET /api/v1/app HTTP/1.1
Host: api.patternhooks.com
Authorization: Bearer sk_live_your_api_key_here
Content-Type: application/json

API Key Types

Key Type	Prefix	Use Case	Permissions
Live Secret Key	`sk_live_`	Production server-side	Full API access
Test Secret Key	`sk_test_`	Development & testing	Full API access (test mode)
Restricted Key	`rk_live_`	Limited access scenarios	Custom permissions

⚠️ Security Warning

Never expose secret keys in client-side code, public repositories, or logs. Use environment variables and secrets management tools. Rotate keys immediately if compromised.

Webhook Signatures

When we deliver webhooks to your endpoints, we include a signature header so you can verify authenticity:

HTTP Headers

webhook-id: msg_7K9mNpQrSt
webhook-timestamp: 1672531200
webhook-signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Always verify signatures before processing webhooks. Our SDKs handle this automatically:

JavaScript

import { Webhook } from '@patternhooks/sdk';

const wh = new Webhook('whsec_your_endpoint_secret');

app.post('/webhooks', express.raw({type: 'application/json'}), (req, res) => {
  try {
    const payload = wh.verify(req.body, {
      'webhook-id': req.headers['webhook-id'],
      'webhook-timestamp': req.headers['webhook-timestamp'],
      'webhook-signature': req.headers['webhook-signature']
    });
    
    // Signature valid! Process the webhook
    handleWebhook(payload);
    res.status(200).send('OK');
  } catch (err) {
    console.error('Invalid signature:', err.message);
    res.status(400).send('Invalid signature');
  }
});

ERROR HANDLING

The API uses conventional HTTP response codes to indicate success or failure:

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	API key lacks required permissions
`404`	Not Found	Resource doesn't exist
`409`	Conflict	Resource already exists (idempotency)
`422`	Unprocessable	Valid JSON but invalid data
`429`	Rate Limited	Too many requests
`500`	Server Error	Something went wrong on our end

Error Response Format

JSON

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "url",
        "message": "Must be a valid HTTPS URL"
      }
    ],
    "requestId": "req_abc123xyz"
  }
}

💡 Request IDs

Every response includes a requestId. Include this when contacting support to help us investigate issues quickly.

NEXT STEPS

Now that you understand the basics, explore these resources to go deeper:

📖

ALL GUIDES

Step-by-step tutorials for common tasks

🔧

API REFERENCE

Complete endpoint documentation

🔌

INTEGRATIONS

Connect with your favorite tools