Send webhooks to external services

Webhooks send a real-time HTTP POST with a JSON payload to a URL you control whenever selected events happen in Onplana. Use them to mirror task changes into another tool, kick off CI jobs, or feed a data warehouse.

Create a webhook

1. Open Integrations in the sidebar and go to the Webhooks tab.

2. Select New Webhook.

3. Give it a Name, enter your Endpoint URL, and tick the Events to subscribe to. The URL must be a public http or https address; private and internal network addresses are rejected.

4. Select Create Webhook. Use the test action on the new webhook’s card to send a sample delivery and confirm your endpoint responds.

Supported events

You can subscribe to any combination of these twelve events:

Tasks	Projects	Other
task.created	project.created	comment.created
task.updated	project.updated	member.added
task.deleted	project.deleted	member.removed
task.status_changed	project.billable_changed
task.preview_ready

Each delivery is a POST with body { "event": "...", "timestamp": "...", "data": { ... } }, and the event name is repeated in the X-Webhook-Event request header.

Verify the signature

Every delivery is signed so your receiver can prove it came from Onplana. The X-Webhook-Signature header carries the HMAC-SHA256 of the raw request body, computed with the webhook’s secret and hex-encoded. To verify, compute the same HMAC over the exact bytes you received and compare the two values with a constant-time comparison:

const crypto = require('crypto')
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))

Each webhook gets its own secret, generated when it is created. The secret is returned only in the API response that creates the webhook and is redacted from every later read, so if your receiver needs to verify signatures, create the webhook through the API (you can also supply your own secret in that call) and store the secret with your other credentials.

Caution

Treat an empty X-Webhook-Signature header as unsigned and reject the request unless the source is otherwise allow-listed.

Delivery and failure handling

• Your endpoint has 10 seconds to respond. Any 2xx status counts as a successful delivery.
• Every webhook card has a Recent Deliveries view showing the latest deliveries with event, HTTP status, and response time.
• Failures increment a per-webhook failure counter; a success resets it to zero. After 10 consecutive failures the webhook stops being delivered to, so a dead endpoint cannot generate endless retries.
• To revive a webhook that hit the failure limit, fix your endpoint and send a test delivery; a successful test resets the counter.

FAQs

Who can manage webhooks? By default, Owners and Admins. This is the organization’s webhook management permission, so you can extend it to Portfolio Managers from the permissions matrix in Organization Settings.

Are failed deliveries retried automatically? No. A delivery is attempted once per event. Build idempotent receivers and use the Recent Deliveries view to spot gaps; the failure counter and test delivery cover recovery.

Can I pause a webhook without deleting it? Yes. Toggle it inactive from its card; the configuration and delivery history are kept, and no events are sent until you re-enable it.