Receive pin events with a webhook in n8n

PinBridge can notify you when a pin publishes or fails. The PinBridge node package does not ship a trigger node, so you receive these events with n8n’s built-in Webhook node and register that node’s URL with PinBridge.

The two events

PinBridge emits exactly two webhook events:

• pin.published — body: {"pin_id", "pinterest_pin_id", "title", "published_at"}.
• pin.failed — body: {"pin_id", "error_code", "error_message"}.

The event name is not in the JSON body. It arrives in the X-PinBridge-Event header. Each delivery also sends X-PinBridge-Delivery-ID and a signature header (below).

Step 1: Add n8n’s Webhook node

1. In a new workflow, add the built-in Webhook node (not a PinBridge node).
2. Set the HTTP method to POST.
3. In the node’s options, turn on Raw Body. You need the exact raw bytes to verify the signature.
4. Copy the Production URL shown on the node. This is the URL PinBridge will call.
5. Activate the workflow so the production URL is live.

Step 2: Register the URL with PinBridge

1. Add a PinBridge node set to Resource = Webhook, Operation = Create.
2. Set Webhook URL to the production URL from step 1.
3. Set Webhook Secret to a random string of 16 to 255 characters. Store it; you need it to verify signatures.
4. Leave Webhook Events at the default pin.published,pin.failed, or narrow it to one.
5. Leave Enabled on.
6. Execute. The node calls POST /v1/webhooks and registers the delivery URL.

Delivery behavior: a delivery succeeds on any 2xx response. PinBridge retries up to 5 attempts with exponential backoff (base-2 minutes), and each attempt times out after 30 seconds. Return 2xx quickly from your Webhook node’s workflow.

Step 3: Verify the signature

The signature header is X-PinBridge-Signature. It is an HMAC-SHA256 hex digest computed over the raw JSON request body only (no timestamp, no prefix). To verify:

1. After the Webhook node, add a Crypto node.
2. Set it to HMAC, algorithm SHA256, output HEX.
3. Set the value to the raw body from the Webhook node, and the secret to the secret you set in step 2.
4. Add an IF node that compares the Crypto node’s output to ={{$json["headers"]["x-pinbridge-signature"]}}.
5. On the true branch, continue. On the false branch, reject the request (the body was tampered with or the secret is wrong).

Because the signature covers the raw body only, verify before any node reshapes the JSON.

Step 4: Branch by event

Read the event name from the header and route with an IF or Switch node:

• Compare ={{$json["headers"]["x-pinbridge-event"]}} against pin.published and pin.failed.
• On pin.published, use pin_id, pinterest_pin_id, title, and published_at.
• On pin.failed, use pin_id, error_code, and error_message. See Troubleshooting for the error codes.

If you prefer to branch on the body, pin.failed carries error_code and pin.published does not, but the header is the reliable signal.

Manage the subscription

The Webhook resource also supports List (GET /v1/webhooks), Get, Update (PATCH /v1/webhooks/{webhookId}), and Delete. Use Update to rotate the secret or toggle the subscription without recreating it. See Node reference.

Verify it worked

Publish a test pin (see Publish your first pin). When it reaches published, your Webhook node should fire with X-PinBridge-Event: pin.published and a matching signature. If nothing arrives, confirm the workflow is active and the registered URL is the production URL.

Next steps

• Publish your first pin — generate an event to test against.
• Node reference — every Webhook operation and endpoint.
• Troubleshooting — why events might not arrive.