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.
An integration can have up to 25 subscriptions.
What a delivery looks like
Quiva sends aPOST 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.- Build the signed content:
<webhook-id>.<webhook-timestamp>.<raw body>. - Take the signing secret, remove the
whsec_prefix and base64-decode the rest. That is the key. - Compute an HMAC-SHA256 of the signed content and base64-encode it.
- Compare it in constant time against every
v1,entry inwebhook-signature. Accept the request if any entry matches. - 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.versionis 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
originis the subscription’s own integration is not sent to it. - If
sync_keyappears inchanged_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 sendPATCH 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 typetest. 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.
Related
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.