Webhooks or polling?
FieldTask can tell your system when customers, customer locations, jobs and members change, in two ways:
- Webhooks: FieldTask sends each change to an HTTPS endpoint you run.
- The event feed: your system asks for changes with
GET /public/v1/events, using a cursor to continue where it left off.
Both deliver the same event object: which record changed, its new revision and the names of the fields that changed. Neither includes field values, so after an event you read the current record with the REST API.
Webhooks and the event feed are part of a review contract that hasn't been released. FieldTask enables them separately from the rest of the API.
What both need
- API access for your organization, requested by an owner or admin in Settings → API connections.
- Change sync enabled by FieldTask, and your organization enrolled. FieldTask enrolls your organization for each record family separately: customers, customer locations, jobs and members. Ask FieldTask which families are enabled for you.
- Read permissions on the connection for each family you want. Customer locations need both
customer_locations:readandcustomers:read.
Webhooks also need to be enabled by FieldTask.
What neither covers
Events exist only for customers, customer locations, jobs and members. There are no events for quotes, invoices, products and prices, job items, member invitations or timesheets. To track those, list them periodically with the REST API.
Comparison
| Webhooks | Event feed | |
|---|---|---|
| How changes arrive | FieldTask sends a signed POST to your HTTPS endpoint for each event. | You request pages of events. |
| What you run | A public HTTPS receiver on port 443. | Any process that can call the REST API. |
| Setup | An owner or admin adds the webhook in Settings → API connections, and your receiver answers a signed challenge. | None beyond a REST credential. |
| Credential you hold | A signing secret, used to verify each request. | An API token or OAuth access token. |
| Order | Not guaranteed. Retries can deliver an older event after a newer one. | In the order FieldTask added events to the feed. |
| Duplicates | Possible. Retries and replays reuse the same event ID. | Possible if you request the same cursor again. |
| If your side is down | FieldTask retries for up to 12 attempts or 24 hours, then pauses the webhook. You resume it and choose deliveries to retry. | Nothing is lost while your cursor is valid. Cursors expire after 30 days. |
| If the connection's permissions change | The webhook pauses and can't be resumed. Add a new webhook and resynchronize. | Your cursor stops working. Start a new cursor and resynchronize. |
| Usage allowance | Webhook deliveries aren't API requests. Reading the changed records is. | Every feed request counts against a daily event-feed allowance, including empty pages. |
When to use which
Use webhooks when you want to react to changes soon after they happen and can run a public HTTPS endpoint. Read Receive webhooks.
Use the event feed when you can't accept inbound requests, for example behind a firewall, or when you sync on a schedule. Read Event feed.
Use both when you want webhooks for speed and the feed as a safety net. They're independent: the feed doesn't know which events your webhook received. A common pattern is to let webhooks trigger work as events arrive, and periodically read the feed to catch anything missed while a webhook was paused. Your event handling must then ignore events it has already applied, by event_id or by comparing revision.
Either way
- Start with a full copy. Before relying on events, read every record you need with the list endpoints. With the feed, take a cursor with
after=nowfirst, then backfill. With webhooks, delivery starts when your receiver is verified; changes before that aren't sent. - Read the current record. Events carry field names, not values. Read the record with
GET /public/v1/customers/{id},GET /public/v1/customer-locations/{id},GET /public/v1/jobs/{id}orGET /public/v1/members/{id}. - Handle deletes.
*.deletedevents mean the record is no longer visible through the API. Remove it from your copy. - Use
revision. Ignore an event whose revision isn't newer than the one you've stored. - Plan for a resync. If history expires or permissions change, you rebuild your copy from the list endpoints and start again.