Webhook source

A webhook source gives you a URL. Any system that can send an HTTP request can send events to it.

POST https://hooksnode.com/p/<source-id>

The default source of a project has the same ID as the project.

Send an event

curl -X POST https://hooksnode.com/p/<source-id> \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order_9311_paid" \
  -d '{"event":"order.paid","order_id":"9311"}'

await fetch("https://hooksnode.com/p/<source-id>", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Idempotency-Key": "order_9311_paid",
  },
  body: JSON.stringify({ event: "order.paid", order_id: "9311" }),
});

import requests

requests.post(
    "https://hooksnode.com/p/<source-id>",
    headers={"X-Idempotency-Key": "order_9311_paid"},
    json={"event": "order.paid", "order_id": "9311"},
)

req, _ := http.NewRequest("POST", "https://hooksnode.com/p/<source-id>",
	strings.NewReader(`{"event":"order.paid","order_id":"9311"}`))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Idempotency-Key", "order_9311_paid")
http.DefaultClient.Do(req)

hooksnode keeps the body byte for byte, and keeps the request headers. The body can be up to 4 MiB. It does not have to be JSON, but filters and transforms need a JSON object.

Responses

Status	Body	Meaning
`200`	`{"status":"accepted","callback_id":…,"enqueued":…}`	Saved and queued.
`200`	`{"status":"buffered","callback_id":…}`	Pro project with no destination. See buffered events.
`200`	`{"status":"duplicate","message":"already accepted"}`	An unsigned source already stored this `X-Idempotency-Key`. A signed source drops an exact resend (the same body and signature) within 10 minutes.
`400`	`{"error":"no destinations configured"}`	Free project with no destination.
`401`	`{"error":"invalid signature"}`	Signature check failed.
`402`	`{"error":…}`	No credits, unpaid plan, or source over the plan limit.
`404`		No such source, or the source has no URL.
`423`	`{"error":"source paused"}`	The source is paused.
`429`		Over the source rate limit. Wait for `Retry-After` (60 s).
`503`		A short outage on our side. Retry after `Retry-After`.

Most providers retry on 5xx and 429. Do not drop an event when you get these codes.

Check signatures on the way in

You can make hooksnode refuse events that are not signed with a secret. Use this for your own senders.

Open the source and turn on Signing. hooksnode makes a secret.
In your sender, compute an HMAC-SHA256 of the raw body with the secret.
Send it in the X-Webhook-Signature header as sha256=<hex>.

BODY='{"event":"order.paid"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -X POST https://hooksnode.com/p/<source-id> \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=$SIG" \
  -d "$BODY"

A missing or wrong signature gets 401.

For Paystack, Flutterwave, Stripe or Meta, pick that provider’s signature preset and paste its secret. hooksnode checks the provider’s own header. For Paystack, paste the webhook signing secret (whsec_…) or the secret key (sk_…) as given. Paystack-Signature is checked when present (t=<unix>, v1=<key id>:<hex HMAC-SHA512 of "<t>.<body>">, 300 seconds, several v1 values during rotation). x-paystack-signature (HMAC-SHA512 of the body) is checked only when Paystack-Signature is absent. Presets are in internal/service/sigverify/sigverify.go. hooksnode still forwards those signature headers. It does not forward Cookie, Authorization or X-Forwarded-*. Set those on the destination if you need them. See Destination rules.

Old `/proxy` URLs

POST /proxy/:userID is removed. Callers get 410 Gone. Point them at POST /p/<source-id> instead. The default source id is the project id.

Rate limit

Each source takes up to 1,000 events a minute by default. On a Pro project you can raise the limit up to 1,000,000 a minute. Over the limit, hooksnode answers 429 with Retry-After: 60.

Get started

Sources

Destinations

Delivery

Monitoring

Local development

Workspaces

Send an event

Responses

Check signatures on the way in

Old `/proxy` URLs

Rate limit

​Send an event

​Responses

​Check signatures on the way in

​Old /proxy URLs

​Rate limit

Send an event

Responses

Check signatures on the way in

Old `/proxy` URLs

Rate limit