Using Webhooks with ClientPress

ClientPress can send an HTTP POST request to any URL whenever something happens in a portal. This lets you connect ClientPress to external tools, automation platforms, and custom systems without any polling or manual effort.

---

Setting Up a Webhook #

1. Go to Settings → ClientPress → Advanced → Webhooks
2. Enter your Endpoint URL — the URL that should receive the webhook
3. Optionally enter a Signing Secret to verify requests (recommended)
4. Under Events to Send, check the events you want to fire
5. Save settings

Leave the Endpoint URL blank to disable webhooks entirely.

---

Supported Events #

• portal.created — Fires when a new portal is published
• file.uploaded — Fires when a file is added to the Files tab
• file.approved — Fires when a file is approved
• file.rejected — Fires when a file is rejected
• task.created — Fires when a new task is created
• task.completed — Fires when a task is marked complete
• message.sent — Fires when a message is posted in Discussion
• invite.accepted — Fires when a client accepts an invitation and creates their account
• board.topic_posted — Fires when a new topic is posted on the Message Board
• deliverable.uploaded — Fires when a deliverable is uploaded
• deliverable.in_review — Fires when a deliverable is sent for client review
• deliverable.approved — Fires when a client approves a deliverable
• deliverable.revision_requested — Fires when a client requests a revision on a deliverable

---

Payload Format #

All webhook requests are HTTP POST with a JSON body and the following structure:

{
  "event":      "task.completed",
  "portal_id":  42,
  "portal_url": "https://your-site.com/client-portal/acme-corp/",
  "timestamp":  "2024-01-18T14:22:00+00:00",
  "data":       { }
}

The data object contains event-specific fields. For example, task.completed includes the task ID, title, and list ID. invite.accepted includes the new user’s ID, email, and display name.

---

Request Headers #

Every webhook request includes these headers:

• Content-Type — application/json
• X-CP-Event — The event slug (e.g. task.completed)
• X-CP-Portal-ID — The portal’s post ID
• X-CP-Delivery — A unique UUID for this delivery
• User-Agent — ClientPress/{version}; https://clientpress.io
• X-CP-Signature — Present only if a signing secret is configured

---

Verifying Webhook Signatures #

If you configure a signing secret, each request includes an X-CP-Signature header formatted as:

sha256={hex_encoded_hmac}

The HMAC is computed using SHA-256 over the raw JSON request body, signed with your secret. To verify a request on your endpoint:

1. Read the raw request body (before parsing JSON)
2. Compute HMAC-SHA256(body, your_secret)
3. Compare the result to the value after sha256= in the header
4. Use a constant-time comparison function to prevent timing attacks

Requests that fail signature verification should be rejected.

---

Delivery Behavior #

• Webhooks are sent fire-and-forget — they do not block or slow down portal actions
• There is no automatic retry if your endpoint is unavailable or returns an error
• Use the X-CP-Delivery UUID to detect and deduplicate any requests if needed
• Your endpoint should respond with a 2xx status code to acknowledge receipt

---

Testing Your Webhook #

The easiest way to test is to use a tool like Webhook.site or RequestBin as a temporary endpoint. Paste the URL into the Webhook URL setting, trigger an event in a portal, and inspect the received payload.