⏱️ 10 min read📊 Beginner📅 Updated Jan 2026

QUICK START GUIDE

This guide walks you through sending your first webhook with PatternHooks. By the end, you'll understand the core concepts and have a working integration. No prior webhook experience required.

IN THIS GUIDE

Prerequisites
Step 1: Get Your API Key
Step 2: Install the SDK
Step 3: Create an Application
Step 4: Add an Endpoint
Step 5: Send Your First Event
Step 6: Verify Delivery
Next Steps

0PREREQUISITES

Before you begin, make sure you have the following:

👤

PatternHooks Account
Sign up free — no credit card required

💻

Node.js 16+
Or Python 3.8+, Go 1.18+, Ruby 2.7+

🔗

Endpoint URL
We'll create a test one using webhook.site

📝

Code Editor
VS Code, Sublime, or your favorite

1GET YOUR API KEY

Your API key authenticates requests to the PatternHooks API. Each key is scoped to either test or live mode.

Log into the PatternHooks Dashboard
Navigate to Settings → API Keys
Click Create API Key
Select Test Mode (we'll use live mode later)
Copy the key — it starts with sk_test_

⚠️ Keep Your Key Secret

Never commit API keys to version control or expose them in client-side code. Use environment variables instead: export PATTERNHOOKS_API_KEY=sk_test_xxx

2INSTALL THE SDK

We offer official SDKs for all major languages. Choose your preferred language:

Node.js

Terminal

npm install @patternhooks/sdk
# or
yarn add @patternhooks/sdk
# or
pnpm add @patternhooks/sdk

Python

Terminal

pip install patternhooks
# or with poetry
poetry add patternhooks

Go

Terminal

go get github.com/patternhooks/patternhooks-go

Ruby

Terminal

gem install patternhooks
# or in Gemfile
gem 'patternhooks', '~> 2.1'

💡 TypeScript Support

The Node.js SDK includes full TypeScript definitions. No additional packages needed — just import and go!

3CREATE AN APPLICATION

Applications are containers for webhooks, typically representing one of your customers. Let's create one:

JavaScript

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

// Initialize with your API key
const ph = new PatternHooks(process.env.PATTERNHOOKS_API_KEY);

// Create an application for a customer
const app = await ph.application.create({
  name: 'Acme Corporation',        // Display name
  uid: 'customer_12345',           // Your internal ID (optional but recommended)
  metadata: {                      // Custom data (optional)
    plan: 'pro',
    signupDate: '2025-01-15'
  }
});

console.log('✓ Application created:', app.id);
// Output: ✓ Application created: app_2X8BfDj3K4mN

The uid field is optional but highly recommended. It allows you to look up applications by your internal customer ID later, which is much more convenient than storing our app IDs.

4ADD AN ENDPOINT

Endpoints are the URLs where webhooks will be delivered. For testing, we'll use webhook.site — a free service that gives you a unique URL to inspect incoming requests.

Visit webhook.site
Copy your unique URL (looks like https://webhook.site/abc-123-...)
Create an endpoint:

JavaScript

const endpoint = await ph.endpoint.create(app.id, {
  url: 'https://webhook.site/your-unique-id',  // Your webhook.site URL
  description: 'Test endpoint for development',
  
  // Only receive these event types (optional)
  filterTypes: [
    'order.created',
    'order.updated',
    'payment.completed'
  ],
  
  // Rate limit to 10 req/sec for this endpoint (optional)
  rateLimit: 10,
  
  // Custom headers to include (optional)
  headers: {
    'X-Custom-Header': 'my-value'
  }
});

console.log('✓ Endpoint created');
console.log('  URL:', endpoint.url);
console.log('  Secret:', endpoint.secret);  // Save this for verification!

📝 Save the Signing Secret

The endpoint's signing secret (whsec_...) is used to verify webhook authenticity. Store it securely — you'll need it to verify incoming webhooks on your server.

5SEND YOUR FIRST EVENT

Now for the exciting part — let's send a webhook!

JavaScript

const message = await ph.message.create(app.id, {
  eventType: 'order.created',
  
  // Optional: provide your own event ID for idempotency
  eventId: 'evt_' + Date.now(),
  
  // The actual webhook payload
  payload: {
    orderId: 'ord_abc123',
    customer: {
      id: 'cus_xyz789',
      email: 'jane@example.com',
      name: 'Jane Doe'
    },
    items: [
      {
        sku: 'WIDGET-001',
        name: 'Premium Widget',
        quantity: 2,
        unitPrice: 4999
      }
    ],
    subtotal: 9998,
    tax: 800,
    total: 10798,
    currency: 'usd',
    createdAt: new Date().toISOString()
  }
});

console.log('✓ Event sent!');
console.log('  Message ID:', message.id);
console.log('  Event Type:', message.eventType);

That's it! PatternHooks will now:

Sign the payload with the endpoint's secret
Deliver the webhook to the endpoint URL
Automatically retry if the endpoint is unavailable
Record the delivery attempt for monitoring

6VERIFY DELIVERY

Let's confirm the webhook was delivered successfully:

Option A: Check webhook.site

Go back to your webhook.site page. You should see the incoming request with:

The JSON payload you sent
Headers including webhook-id, webhook-timestamp, and webhook-signature
Content-Type: application/json

Option B: Check the Dashboard

Go to the PatternHooks Dashboard
Navigate to Applications → Acme Corporation → Messages
You'll see your message with delivery status

Option C: Check via API

JavaScript

// Get message delivery attempts
const attempts = await ph.messageAttempt.list(app.id, message.id);

for (const attempt of attempts.data) {
  console.log(`Endpoint: ${attempt.endpointId}`);
  console.log(`Status: ${attempt.status}`);           // 'success' or 'fail'
  console.log(`Response Code: ${attempt.responseStatusCode}`);
  console.log(`Latency: ${attempt.responseDurationMs}ms`);
}

🎉 Congratulations!

You've successfully sent your first webhook with PatternHooks! You now understand applications, endpoints, and messages — the core concepts of the platform.

NEXT STEPS

Now that you have the basics down, here's what to explore next:

Verify Webhook Signatures — Essential for security in production
Configure Retry Policies — Customize retry behavior for your needs
Local Development — Test webhooks on localhost with our CLI
API Reference — Full documentation for all endpoints
Handle Idempotency — Safely process duplicate webhooks

← All Guides Verify Signatures →