Skip to main content
A webhook subscription pushes task events from your Spaces to an HTTPS endpoint you control. Each delivery is signed, so your endpoint can prove the request came from QuivaWorks. If your endpoint is down, deliveries are retried for about a day. Subscriptions belong to an API integration, so they can only cover Spaces where that integration holds tasks:read. The events are the same ones the changes feed returns.
A subscription’s endpoint does not have to be yours. When you connect a tracker, the connection creates a subscription whose URL is its own signed sync address on your gateway, and the sync engine receives each event, verifies it and pushes the change to the tracker. Those subscriptions appear under the connection’s integration and in its Delivery log. Leave them as they are.

Create a subscription

1

Open the integration

Go to Account, then Connections, then API integrations, and open the integration.
2

Add a subscription

In Subscriptions, click Add. Enter the Endpoint URL, tick the Spaces to cover, and tick the Events you want. Leave every event unticked to receive all of them.
3

Copy the signing secret

A dialog shows the signing secret once. Store it where your endpoint can read it.
You can also create one with the API. Admin routes need a root or admin session.
An integration can have up to 25 subscriptions.

What a delivery looks like

Quiva sends a POST with a 10-second timeout. The body is the event JSON, the same shape the feed returns, with Content-Type: application/json.

Verify the signature

Signatures follow the Standard Webhooks scheme. Always verify before you trust a request, and verify the raw bytes of the body before you parse JSON.
  1. Build the signed content: <webhook-id>.<webhook-timestamp>.<raw body>.
  2. Take the signing secret, remove the whsec_ prefix and base64-decode the rest. That is the key.
  3. Compute an HMAC-SHA256 of the signed content and base64-encode it.
  4. Compare it in constant time against every v1, entry in webhook-signature. Accept the request if any entry matches.
  5. Reject a timestamp more than 5 minutes away from your clock.

Delivery guarantees

  • At least once, and not ordered. A retry can arrive after a later event. Each delivery carries the whole task, so apply a task event only if task.version is higher than the version you already hold for that task, and discard the rest.
  • Remove duplicates by webhook-id. This matters most for comment and action events, which have no version to compare.
  • No echo. An event whose origin is the subscription’s own integration is not sent to it.
  • If sync_key appears in changed_fields, the task joined or left a connected account. Reset your “newer than” check for that task.

How your response is treated

Retries

A failed delivery is retried after 30 seconds, 1 minute, 5 minutes, 15 minutes, 1 hour, 2 hours, 4 hours, 8 hours and 8 hours: ten attempts in about 24 hours. An event that uses them all is dropped from the queue and recorded in the log. A failing subscription does not cause other subscriptions to receive the event twice.

Auto-pause

A subscription pauses itself after 50 failures in a row, or when its first failure is more than 24 hours old. Account admins get one email when that happens, and the subscription shows Paused with the reason. To resume, open the subscription’s menu and choose Resume. That clears the failure counts. Resuming is refused while the integration is disabled, and enabling the integration does not resume its subscriptions, so do both. Delivery also re-checks, within about 30 seconds, that the integration is still enabled and still holds tasks:read on the event’s Space. Removing tasks:read on a Space takes it out of the integration’s subscriptions.

Rotate the signing secret

Choose Rotate signing secret in the subscription’s menu, or send PATCH with {"rotate_secret": true}. The new secret is shown once. For the next 24 hours each delivery carries two signatures, one per secret, so you can deploy the new secret without dropping events. Your verifier already handles this, because it accepts any matching entry.

Test, replay and the delivery log

In the subscription’s menu, Send test event sends a signed event with the type test. It reaches paused subscriptions and does not change failure counts. Deliveries and replay opens the delivery log, newest first. Each row shows the event, its status (sending, delivered, retrying or failed), the attempt count, the last response code, the latency and a short excerpt of your response. Rows are kept for 30 days. To resend history, enter a From cursor and an optional To cursor and click Replay. Cursors are the values shown in the log or returned by the changes feed. Replay and test events run in the background. Read the outcome in the delivery log.

Task sync

External ids, versions and the changes feed.

API integrations

Create the integration a subscription belongs to.

Webhook trigger

Receive and verify these events inside a flow.

Errors and limits

Codes returned by the subscription routes.