Skip to content

quickstart.mdx

Latest commit

 

History

History
183 lines (138 loc) · 4.07 KB

quickstart.mdx

File metadata and controls

183 lines (138 loc) · 4.07 KB
title Quickstart
description Start scheduling webhooks in under 2 minutes

This guide walks you through setting up Posthook, connecting your local environment, and sending your first scheduled hook.

Prefer an interactive guide? You can follow this same walkthrough interactively in the [Posthook Dashboard](https://posthook.io/app/home).

1. Log In

Connect your local development server to Posthook using the CLI. This lets you receive webhooks locally without tunneling tools like ngrok.

npx posthook login
yarn dlx posthook login
pnpm dlx posthook login

You will be prompted to enter your API Secret Key. You can find this in the Settings page of your project in the Dashboard.

2. Start the Listener

Start the Posthook listener to forward webhooks to your local application.

npx posthook listen --forward http://localhost:3000

Replace http://localhost:3000 with the base URL of your local server.

The listener connects to Posthook via WebSocket. It receives webhooks and forwards them to your specified local URL.

3. Install the SDK (Optional)

Install an official SDK for a streamlined experience. You can also use curl directly.

npm install @posthook/node
pip install posthook-python
go get github.com/posthook/posthook-go

4. Send a Test Hook

In a new terminal, schedule a test webhook to fire in 5 seconds.

import Posthook from '@posthook/node';
const posthook = new Posthook('phk_your_api_key');

const hook = await posthook.hooks.schedule({
  path: '/webhooks/posthook/send-reminder',
  postIn: '5s',
  data: {
    user_id: 'usr_123',
    reminder_id: 'rem_456'
  }
});

console.log('Scheduled:', hook.id);
from posthook import Posthook

client = Posthook("phk_your_api_key")

hook = client.hooks.schedule(
    path="/webhooks/posthook/send-reminder",
    post_in="5s",
    data={
        "user_id": "usr_123",
        "reminder_id": "rem_456"
    }
)

print("Scheduled:", hook.id)
client, _ := posthook.NewClient("phk_your_api_key")

hook, _, _ := client.Hooks.Schedule(context.Background(), &posthook.HookScheduleParams{
    Path:   "/webhooks/posthook/send-reminder",
    PostIn: "5s",
    Data: map[string]string{
        "user_id":     "usr_123",
        "reminder_id": "rem_456",
    },
})

fmt.Println("Scheduled:", hook.ID)
curl -X POST https://api.posthook.io/v1/hooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $POSTHOOK_API_KEY" \
  -d '{
    "path": "/webhooks/posthook/send-reminder",
    "postIn": "5s",
    "data": {
      "user_id": "usr_123",
      "reminder_id": "rem_456"
    }
  }'

You can find your API Key in the Settings page of your project in the Dashboard.

Verification

Check your posthook listen terminal. You should see the hook arrive when it fires:

2026-01-01 12:00:00 [200 OK] POST /webhooks/posthook/send-reminder

5. Check the Dashboard

Open the Activity page in the Dashboard. You can inspect the full payload, view delivery timing, and check response details for any hook.

Next Steps

Understand the full hook lifecycle from scheduling to delivery. Handle deliveries in your app with framework-specific examples. Verify the `Posthook-Signature` to ensure requests are genuine. Explore the full API to schedule, list, and manage your hooks.