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.

Best practices

1. Subscribe to the smallest event set that meets your need. A webhook subscribing to every event firehose gets noisy; pick precise events.
2. Always verify signatures in production. Skipping signature verification lets anyone POST to your endpoint. Use HMAC-SHA256 + constant- time comparison.
3. Build idempotent receivers. Onplana doesn’t retry, but networks have hiccups. Receivers that handle duplicate events correctly avoid weird state.
4. Monitor delivery health. Recent Deliveries shows pass/fail rates. A webhook climbing toward the 10-failure cap needs intervention before it dies.
5. Document the contract internally. Which events fire what shape, who receives them, what they trigger. New team members can reverse-engineer it, but documentation is faster.

Troubleshooting / common pitfalls

• Test delivery returned 404. Endpoint URL wrong. Verify the path in the URL
  • that the server is up.
• Test delivered but signature didn’t match. Re-check secret storage; you may be hashing the URL-encoded body instead of raw bytes.
• All deliveries failing. Endpoint outage. Fix it; send test delivery to reset failure counter.
• Webhook stopped firing. Hit 10- failure cap. Fix endpoint + test delivery.
• Private network URL rejected. Onplana validates URLs and blocks RFC1918 private addresses. Use a publicly addressable proxy (ngrok, Cloudflare Tunnel) for testing internal endpoints.

How this combines with other features

• Webhooks + Workflows. Workflows can call webhooks as a step. See Build a workflow.
• Webhooks + Audit log. Webhook create/update/delete events go to the audit log. See Read audit logs.
• Webhooks + Integrations. Onplana webhooks are the outbound integration primitive. Combine with inbound receivers (Slack incoming-webhook, CI, etc.).
• Webhooks + API tokens. API tokens are the inbound complement; together they cover bidirectional integration.

Coming from another tool

Tool	Mapping
GitHub webhooks	Direct concept; HMAC-SHA256 signed
Stripe webhooks	Direct
Linear webhooks	Direct
Slack outgoing webhooks	Direct
ServiceNow REST messages	Direct

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.

Can I customize the payload shape? No — the payload shape is fixed per event for consistency. To reshape, use a middleware (Zapier, n8n) between Onplana and your endpoint.

Is there an event firehose webhook (all events)? No — you subscribe to specific events. Subscribe to all 12 if you want firehose behavior.

Can I see what payload was sent? Yes — Recent Deliveries shows the request body. Useful for debugging.

Related

• Build a workflow — workflows can call webhooks as a step
• Create API tokens — inbound integration
• Read audit logs — webhook events are audited