Receive webhooks

A FieldTask webhook sends a signed HTTPS POST to your receiver each time a customer, customer location, job or member changes. Each request body is one event.

Preview

Webhooks are part of a review contract that hasn't been released. FieldTask enables them separately from the rest of the API.

Before you start

• Webhooks and change sync enabled by FieldTask, with your organization enrolled for each record family you want. See Webhooks or polling?.

• An organization owner or admin to add and manage the webhook in the FieldTask app. Webhooks can't be managed with an API token.

• An API connection with read permissions for each family the webhook sends. A webhook belongs to one connection and is limited by its permissions:

  Family	Permissions the connection needs
  Customers	customers:read
  Customer locations	customer_locations:read and customers:read
  Jobs	jobs:read
  Members	members:read

• A receiver that meets the requirements below, running with the signing secret before you verify it.

Receiver requirements

FieldTask only delivers to a receiver that meets all of these:

Requirement	Detail
HTTPS on port 443	The URL must start with https:// and use port 443, the default. Other ports aren't accepted. The certificate must be valid for the host name.
Public address	The host name must resolve only to public IP addresses. Private, loopback and reserved addresses are rejected.
Plain URL	Up to 2,048 characters, with no user name or password and no #fragment. A query string is allowed.
Fast response	The whole attempt, including connecting, TLS and reading your response, must finish within 5 seconds.
Small, uncompressed response	Your response body must be at most 4,096 bytes and must not be compressed. A larger or compressed response counts as a failure.
No redirects	Redirects aren't followed. A 3xx response is a failed attempt.

Each request is a POST with Content-Type: application/json, a body of at most 16 KiB, and the headers webhook-id, webhook-signature, webhook-timestamp.

To use a different URL later, add a new webhook. A webhook's URL can't be changed.

Add a webhook

1. Go to Settings → API connections, choose Manage for the connection, and in its Webhooks section choose Manage.
2. Choose Add webhook.
3. Enter the Receiver URL and select the Resources to send: Customers, Customer locations, Jobs and Members. Only families the connection can read are offered. Choose Add webhook.
4. Copy the Signing secret. It starts with whsec_. It's shown once and can't be displayed again.
5. Install the secret on your receiver and make sure the receiver is running.
6. Select I have saved the secret and installed it on the receiver., choose Continue, then Confirm.

FieldTask then sends a signed verification challenge to your receiver. If your receiver answers correctly, the webhook becomes Active. If it doesn't, the webhook stays Pending; fix the receiver and choose Verify receiver in Delivery details.

• You have 15 minutes from adding the webhook, and up to 5 verification attempts. After that, choose Disable webhook and add a new one. Do the same if you lose the secret before verifying.
• Delivery starts from the moment verification succeeds. Changes made before that aren't sent, so backfill your copy with the list endpoints.
• A connection can have up to 10 webhooks that aren't disabled.

Answer the verification challenge

The challenge is a signed POST like any other delivery, with this body:

{"challenge":"EXAMPLE_CHALLENGE","type":"webhook.verification"}

Verify the signature, then reply within 5 seconds with any 2xx status and a body that is exactly:

{"challenge":"EXAMPLE_CHALLENGE"}

The reply is compared byte for byte: compact JSON, the challenge value copied unchanged, no spaces and no trailing newline. The samples below do this.

FieldTask sends a new challenge whenever it needs to confirm your receiver: when you add a webhook, resume or replay deliveries, and activate a new signing secret.

Verify each request

Every request is signed with the Standard Webhooks scheme. Use a standardwebhooks library rather than writing the check yourself.

Header	Contains
webhook-id	The event ID. For deliveries it's the same as the body's event_id.
webhook-timestamp	When this attempt was signed, in seconds since the Unix epoch.
webhook-signature	One or more signatures, separated by spaces, each in the form v1, followed by a Base64 HMAC-SHA256 value.

The signature covers the webhook-id, the webhook-timestamp and the raw request body, exactly as received. Verify before you parse:

• Read the body as bytes. Don't parse it to JSON and serialize it again before verifying; a different byte sequence fails verification.
• If your framework parses JSON automatically, read the raw body instead, for example request.get_data() in Flask or express.raw({ type: 'application/json' }) in Express.
• Reject requests that fail verification with a 4xx status, and never with 410, which pauses the webhook.

Set FIELDTASK_WEBHOOK_SECRETS to your signing secret. During a secret rotation, set it to both secrets separated by a space. Every sample below reads it and tries each secret.

The Python and Node.js samples are complete receivers. The others give you a verify function and a handler that returns the status and body to send; call it from your web framework with the raw body and the request headers.

Python

Install the libraries with pip install standardwebhooks flask.

receiver.py

import json
import os
from concurrent.futures import ThreadPoolExecutor

from flask import Flask, Response, request
from standardwebhooks import Webhook, WebhookVerificationError

# One or more signing secrets (whsec_...), separated by spaces.
WEBHOOKS = [Webhook(secret) for secret in os.environ["FIELDTASK_WEBHOOK_SECRETS"].split()]
SIGNED_HEADERS = ("webhook-id", "webhook-timestamp", "webhook-signature")


def verify_delivery(raw_body, headers):
    """Return the parsed body, or raise if no secret verifies the request."""
    signed = {name: headers.get(name, "") for name in SIGNED_HEADERS}
    error = None
    for webhook in WEBHOOKS:
        try:
            return webhook.verify(raw_body, signed)
        except (WebhookVerificationError, ValueError) as exc:
            error = exc
    raise error


app = Flask(__name__)
executor = ThreadPoolExecutor(max_workers=4)  # use your job queue in production
processed = set()  # use a durable store in production


def handle_event(event):
    if event["event_id"] in processed:
        return  # a retry or replay you've already handled
    processed.add(event["event_id"])
    # Read the current record with the REST API, or remove it if event["tombstone"].
    print(event["event_type"], event["resource"]["id"], event["resource"]["revision"])


@app.post("/fieldtask/webhooks")
def receive():
    raw_body = request.get_data()  # the exact bytes FieldTask signed
    try:
        message = verify_delivery(raw_body, request.headers)
    except (WebhookVerificationError, ValueError):
        return Response(status=400)
    if message.get("type") == "webhook.verification":
        # Reply with exactly {"challenge":"..."}: compact JSON and nothing else.
        reply = json.dumps({"challenge": message["challenge"]}, separators=(",", ":"))
        return Response(reply, status=200, content_type="application/json")
    executor.submit(handle_event, message)  # acknowledge first, then process
    return Response(status=204)

Node.js

Install the library with npm install standardwebhooks.

verify.mjs

import { Webhook } from 'standardwebhooks';

// One or more signing secrets (whsec_…), separated by spaces.
const webhooks = process.env.FIELDTASK_WEBHOOK_SECRETS.trim().split(/\s+/).map((secret) => new Webhook(secret));

// rawBody: a Buffer with the request body exactly as received.
// Returns the parsed body. Throws if no secret verifies the request.
export function verifyDelivery(rawBody, headers) {
  const signed = {
    'webhook-id': headers['webhook-id'],
    'webhook-timestamp': headers['webhook-timestamp'],
    'webhook-signature': headers['webhook-signature'],
  };
  let lastError;
  for (const webhook of webhooks) {
    try {
      return webhook.verify(rawBody, signed);
    } catch (error) {
      lastError = error;
    }
  }
  throw lastError;
}

receiver.mjs

// Node.js 18 or later. Put HTTPS on port 443 in front of this server.
import { createServer } from 'node:http';
import { verifyDelivery } from './verify.mjs';

const processed = new Set(); // use a durable store in production

async function handleEvent(event) {
  if (processed.has(event.event_id)) return; // a retry or replay you've already handled
  processed.add(event.event_id);
  // Read the current record with the REST API, or remove it if event.tombstone is true.
  console.log(event.event_type, event.resource.id, event.resource.revision);
}

createServer((request, response) => {
  if (request.method !== 'POST') return response.writeHead(405).end();
  const chunks = [];
  request.on('data', (chunk) => chunks.push(chunk));
  request.on('end', () => {
    const rawBody = Buffer.concat(chunks); // the exact bytes FieldTask signed
    let message;
    try {
      message = verifyDelivery(rawBody, request.headers);
    } catch {
      return response.writeHead(400).end();
    }
    if (message.type === 'webhook.verification') {
      // Reply with exactly {"challenge":"…"}: compact JSON and nothing else.
      response.writeHead(200, { 'Content-Type': 'application/json' });
      return response.end(JSON.stringify({ challenge: message.challenge }));
    }
    response.writeHead(204).end(); // acknowledge first…
    setImmediate(() => handleEvent(message).catch(console.error)); // …then process
  });
}).listen(Number(process.env.PORT ?? 8080));

Ruby

Ruby 3.3 or later. Install the library with gem install standardwebhooks -v 1.1.0.

fieldtask_webhooks.rb

require "json"
require "standardwebhooks"

module FieldTaskWebhooks
  SIGNED_HEADERS = %w[webhook-id webhook-timestamp webhook-signature].freeze

  # One or more signing secrets (whsec_...), separated by spaces.
  def self.secrets = ENV.fetch("FIELDTASK_WEBHOOK_SECRETS").split

  # raw_body: the request body exactly as received. headers: anything that answers
  # headers["webhook-id"], such as Rails' request.headers.
  # Returns the parsed body, or raises if no secret verifies the request.
  def self.verify(raw_body, headers, secrets = self.secrets)
    signed = SIGNED_HEADERS.to_h { |name| [name, headers[name]] }
    error = nil
    secrets.each do |secret|
      return StandardWebhooks::Webhook.new(secret).verify(raw_body, signed)
    rescue StandardWebhooks::WebhookVerificationError => e
      error = e
    end
    raise error
  end

  # Returns [status, body] to send. The block receives each verified event: put it on
  # a queue and process it after responding, once per event_id.
  def self.handle(raw_body, headers, secrets = self.secrets)
    begin
      message = verify(raw_body, headers, secrets)
    rescue StandardWebhooks::WebhookVerificationError
      return [400, ""]
    end
    if message["type"] == "webhook.verification"
      # Reply with exactly {"challenge":"..."}: compact JSON and nothing else.
      return [200, JSON.generate({ "challenge" => message["challenge"] })]
    end
    yield message
    [204, ""]
  end
end

PHP

PHP 8.1 or later. Install the library with composer require standard-webhooks/standard-webhooks:1.0.2.

FieldTaskWebhooks.php

<?php
use StandardWebhooks\Exception\WebhookVerificationException;
use StandardWebhooks\Webhook;

final class FieldTaskWebhooks
{
    /** @param string[] $secrets One or more signing secrets (whsec_...). */
    public function __construct(private array $secrets)
    {
    }

    public static function fromEnvironment(): self
    {
        return new self(preg_split('/\s+/', trim(getenv('FIELDTASK_WEBHOOK_SECRETS'))));
    }

    /**
     * $rawBody: the request body exactly as received, e.g. file_get_contents('php://input').
     * $headers: lower-case names to values, e.g. array_change_key_case(getallheaders()).
     * Returns the parsed body; throws if no secret verifies the request.
     */
    public function verify(string $rawBody, array $headers): array
    {
        $signed = array_intersect_key($headers, array_flip(['webhook-id', 'webhook-timestamp', 'webhook-signature']));
        $error = null;
        foreach ($this->secrets as $secret) {
            try {
                return (new Webhook($secret))->verify($rawBody, $signed);
            } catch (WebhookVerificationException $e) {
                $error = $e;
            }
        }
        throw $error;
    }

    /**
     * Returns [status, body] to send. $enqueue receives each verified event: put it on a
     * queue and process it after responding, once per event_id.
     */
    public function handle(string $rawBody, array $headers, callable $enqueue): array
    {
        try {
            $message = $this->verify($rawBody, $headers);
        } catch (WebhookVerificationException) {
            return [400, ''];
        }
        if (($message['type'] ?? null) === 'webhook.verification') {
            // Reply with exactly {"challenge":"..."}: compact JSON, slashes not escaped.
            return [200, json_encode(['challenge' => $message['challenge']], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)];
        }
        $enqueue($message);
        return [204, ''];
    }
}

Java

Java 17 or later, with com.standardwebhooks:standardwebhooks:1.2.0 and com.fasterxml.jackson.core:jackson-databind:2.18.2.

FieldTaskWebhooks.java

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.standardwebhooks.Webhook;
import com.standardwebhooks.exceptions.EmptyWebhookSecretException;
import com.standardwebhooks.exceptions.WebhookVerificationException;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.function.Consumer;

public final class FieldTaskWebhooks {
    public record Reply(int status, String body) {}

    private static final ObjectMapper JSON = new ObjectMapper();
    private final List<Webhook> webhooks = new ArrayList<>();

    /** One or more signing secrets (whsec_...), separated by spaces. */
    public FieldTaskWebhooks(String secrets) throws EmptyWebhookSecretException {
        for (String secret : secrets.trim().split("\\s+")) {
            webhooks.add(new Webhook(secret));
        }
    }

    public static FieldTaskWebhooks fromEnvironment() throws EmptyWebhookSecretException {
        return new FieldTaskWebhooks(System.getenv("FIELDTASK_WEBHOOK_SECRETS"));
    }

    /**
     * rawBody: the request body exactly as received, as UTF-8 text. headers: names to
     * values, for example Spring's HttpHeaders. Returns the parsed body; throws if no
     * secret verifies the request.
     */
    public JsonNode verify(String rawBody, Map<String, List<String>> headers)
            throws WebhookVerificationException, IOException {
        WebhookVerificationException error = null;
        for (Webhook webhook : webhooks) {
            try {
                webhook.verify(rawBody, headers);
                return JSON.readTree(rawBody);
            } catch (WebhookVerificationException e) {
                error = e;
            }
        }
        throw error;
    }

    /**
     * Returns the status and body to send. enqueue receives each verified event: put it
     * on a queue and process it after responding, once per event_id.
     */
    public Reply handle(String rawBody, Map<String, List<String>> headers, Consumer<JsonNode> enqueue)
            throws IOException {
        JsonNode message;
        try {
            message = verify(rawBody, headers);
        } catch (WebhookVerificationException e) {
            return new Reply(400, "");
        }
        if ("webhook.verification".equals(message.path("type").asText())) {
            // Reply with exactly {"challenge":"..."}: compact JSON and nothing else.
            String reply = JSON.writeValueAsString(Map.of("challenge", message.get("challenge").asText()));
            return new Reply(200, reply);
        }
        enqueue.accept(message);
        return new Reply(204, "");
    }
}

Go

Install the library with go get github.com/standard-webhooks/standard-webhooks/libraries@v0.0.1.

webhooks.go

package webhooks

import (
	"bytes"
	"encoding/json"
	"errors"
	"io"
	"net/http"
	"strings"

	standardwebhooks "github.com/standard-webhooks/standard-webhooks/libraries/go"
)

type Verifier struct {
	webhooks []*standardwebhooks.Webhook
}

// NewVerifier takes one or more signing secrets (whsec_...), separated by spaces,
// for example os.Getenv("FIELDTASK_WEBHOOK_SECRETS").
func NewVerifier(secrets string) (*Verifier, error) {
	v := &Verifier{}
	for _, secret := range strings.Fields(secrets) {
		wh, err := standardwebhooks.NewWebhook(secret)
		if err != nil {
			return nil, err
		}
		v.webhooks = append(v.webhooks, wh)
	}
	return v, nil
}

// Verify returns the parsed body, or an error if no secret verifies the request.
// rawBody must be the request body exactly as received.
func (v *Verifier) Verify(rawBody []byte, headers http.Header) (map[string]any, error) {
	err := errors.New("no signing secret configured")
	for _, wh := range v.webhooks {
		if err = wh.Verify(rawBody, headers); err == nil {
			var message map[string]any
			return message, json.Unmarshal(rawBody, &message)
		}
	}
	return nil, err
}

// Handler receives deliveries, for example http.Handle("/fieldtask/webhooks", v.Handler(enqueue)).
// enqueue receives each verified event: put it on a queue and process it after
// responding, once per event_id.
func (v *Verifier) Handler(enqueue func(event map[string]any)) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if r.Method != http.MethodPost {
			w.WriteHeader(http.StatusMethodNotAllowed)
			return
		}
		rawBody, err := io.ReadAll(r.Body) // the exact bytes FieldTask signed
		if err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}
		message, err := v.Verify(rawBody, r.Header)
		if err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}
		if message["type"] == "webhook.verification" {
			// Reply with exactly {"challenge":"..."}: compact JSON and nothing else.
			var reply bytes.Buffer
			encoder := json.NewEncoder(&reply)
			encoder.SetEscapeHTML(false)
			encoder.Encode(map[string]any{"challenge": message["challenge"]})
			w.Header().Set("Content-Type", "application/json")
			w.Write(bytes.TrimRight(reply.Bytes(), "\n"))
			return
		}
		enqueue(message)
		w.WriteHeader(http.StatusNoContent)
	})
}

.NET

.NET 8 or later. Install the library with dotnet add package StandardWebhooks.StandardWebhooks --version 1.0.1.

FieldTaskWebhooks.cs

using System.Net;
using System.Text.Encodings.Web;
using System.Text.Json;
using StandardWebhooks;
using StandardWebhooks.Exceptions;

public sealed class FieldTaskWebhooks
{
    private static readonly string[] SignedHeaders = { "webhook-id", "webhook-timestamp", "webhook-signature" };
    private static readonly JsonSerializerOptions ReplyOptions = new() { Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping };
    private readonly List<Webhook> webhooks;

    // One or more signing secrets (whsec_...), separated by spaces.
    public FieldTaskWebhooks(string secrets) =>
        webhooks = secrets.Split(' ', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
            .Select(secret => new Webhook(secret)).ToList();

    public static FieldTaskWebhooks FromEnvironment() =>
        new(Environment.GetEnvironmentVariable("FIELDTASK_WEBHOOK_SECRETS") ?? "");

    // rawBody: the request body exactly as received, as UTF-8 text.
    // header: looks up a request header, for example name => Request.Headers[name] in ASP.NET Core.
    // Returns the parsed body; throws WebhookVerificationException if no secret verifies it.
    public JsonElement Verify(string rawBody, Func<string, string?> header)
    {
        var signed = new WebHeaderCollection();
        foreach (var name in SignedHeaders)
        {
            var value = header(name);
            if (!string.IsNullOrEmpty(value)) signed.Add(name, value);
        }
        WebhookVerificationException? error = null;
        foreach (var webhook in webhooks)
        {
            try
            {
                webhook.Verify(rawBody, signed);
                using var document = JsonDocument.Parse(rawBody);
                return document.RootElement.Clone();
            }
            catch (WebhookVerificationException e)
            {
                error = e;
            }
        }
        throw error ?? new WebhookVerificationException("No signing secret configured");
    }

    // Returns the status and body to send. enqueue receives each verified event: put it
    // on a queue and process it after responding, once per event_id.
    public (int Status, string Body) Handle(string rawBody, Func<string, string?> header, Action<JsonElement> enqueue)
    {
        JsonElement message;
        try
        {
            message = Verify(rawBody, header);
        }
        catch (WebhookVerificationException)
        {
            return (400, "");
        }
        if (message.TryGetProperty("type", out var type) && type.GetString() == "webhook.verification")
        {
            // Reply with exactly {"challenge":"..."}: compact JSON and nothing else.
            var reply = JsonSerializer.Serialize(new { challenge = message.GetProperty("challenge").GetString() }, ReplyOptions);
            return (200, reply);
        }
        enqueue(message);
        return (204, "");
    }
}

Rust

Add standardwebhooks = "1.0.1", http = "1" and serde_json = "1" to Cargo.toml. The HeaderMap is the one frameworks such as axum give you.

webhooks.rs

use http::HeaderMap;
use serde_json::{json, Value};
use standardwebhooks::{Webhook, WebhookError};

pub struct Verifier {
    webhooks: Vec<Webhook>,
}

impl Verifier {
    /// One or more signing secrets (whsec_...), separated by spaces, for example
    /// std::env::var("FIELDTASK_WEBHOOK_SECRETS").
    pub fn new(secrets: &str) -> Result<Self, WebhookError> {
        let webhooks = secrets.split_whitespace().map(Webhook::new).collect::<Result<_, _>>()?;
        Ok(Self { webhooks })
    }

    /// raw_body: the request body exactly as received. Returns the parsed body, or an
    /// error if no secret verifies the request.
    pub fn verify(&self, raw_body: &[u8], headers: &HeaderMap) -> Result<Value, WebhookError> {
        let mut error = WebhookError::InvalidSignature;
        for webhook in &self.webhooks {
            match webhook.verify(raw_body, headers) {
                Ok(()) => return serde_json::from_slice(raw_body).map_err(|_| WebhookError::InvalidPayload),
                Err(e) => error = e,
            }
        }
        Err(error)
    }

    /// Returns the status and body to send. `enqueue` receives each verified event: put
    /// it on a queue and process it after responding, once per event_id.
    pub fn handle(&self, raw_body: &[u8], headers: &HeaderMap, enqueue: impl FnOnce(Value)) -> (u16, String) {
        let message = match self.verify(raw_body, headers) {
            Ok(message) => message,
            Err(_) => return (400, String::new()),
        };
        if message["type"] == "webhook.verification" {
            // Reply with exactly {"challenge":"..."}: compact JSON and nothing else.
            return (200, json!({ "challenge": message["challenge"] }).to_string());
        }
        enqueue(message);
        (204, String::new())
    }
}

Replay protection

The standardwebhooks libraries reject a request whose webhook-timestamp is more than five minutes before or after your server's clock. Keep your clock synchronized. FieldTask signs every attempt with a fresh timestamp, so retries aren't rejected for being old.

Within those five minutes, a captured request could be sent to you again. Recording the event IDs you've processed, as the samples do, makes a repeated request harmless.

Respond quickly, process later

Any 2xx response marks the delivery as delivered. Return it as soon as the request is verified, then do the work afterwards, for example by putting the event on a queue. Reading records from FieldTask or writing to your database before responding risks exceeding the 5 seconds limit, which counts as a failure and causes a retry.

Retries and failures

A delivery attempt fails if your receiver times out, can't be reached, fails the requirements above, or returns any status other than 2xx. FieldTask then tries again with the same event ID and body, and a new signature and timestamp:

After failed attempt	Next attempt no sooner than
1	15–30 seconds
2	30–60 seconds
3	1–2 minutes
4	2–4 minutes
5	4–8 minutes
6	8–16 minutes
7	16–32 minutes
8 to 11	30–60 minutes

Each wait is chosen at random within its range. If you respond 429 or 503 with a Retry-After header in seconds, FieldTask waits at least that long, up to 1 hour.

FieldTask stops after 12 attempts, or 24 hours after the delivery was first queued or last replayed, whichever comes first. The webhook is then paused.

Delivery also ends early in these cases:

• Your receiver returns 410 Gone. The delivery is marked as failed and the webhook pauses. Only return 410 if you want deliveries to stop.
• The record is no longer visible to the connection when an attempt is due. Its created or updated delivery is cancelled. Its deleted event is still delivered.

Before each attempt, FieldTask checks the connection's access again. If the connection was revoked or its permissions changed, delivery stops and the webhook pauses.

FieldTask holds at most 1,000 waiting deliveries per webhook. When that many are waiting, it stops queuing new events until the backlog shrinks. Events aren't dropped; they're queued later.

Duplicates and ordering

The same event can reach you more than once: after a timeout where your receiver did process the request, after a retry, or when someone replays a delivery. Events can also arrive out of order.

• Deduplicate by webhook-id, which equals the event's event_id. Keep processed IDs for at least the history period, because deliveries can be replayed within it.
• Use resource.revision to ignore an event that is older than the state you already have. See Revisions.

Pause, resume and replay

Open Delivery details for a webhook to see its state, its last successful delivery and its recent deliveries, up to 100 per page.

Why a webhook pauses

Reason shown	What happened	What to do
The receiver returned HTTP 410.	Your receiver answered 410.	Fix the receiver, then Resume delivery.
Delivery retry limits were reached.	A delivery failed 12 times or for 24 hours.	Fix the receiver, then Resume delivery and select the failed deliveries to retry.
Connection permissions or sync access changed.	The connection's permissions changed, the connection was revoked, or FieldTask changed sync access for your organization.	This webhook can't be resumed. Disable webhook, add a new one, and resynchronize your copy from the list endpoints.
Required history expired.	Waiting changes are older than the history FieldTask keeps.	This webhook can't be resumed. Resynchronize your copy from the list endpoints, then add a new webhook.
Delivery was paused by an administrator.	Someone chose Pause delivery.	Resume delivery when ready.

When a webhook pauses for any reason other than an administrator's request, the organization's owner and admins get an in-app notification, Webhook delivery paused.

While a webhook is paused:

• Deliveries that were waiting are marked Failed.
• New changes aren't lost. They're sent after you resume, as long as they're still within the history period.

Resume delivery

Resume delivery sends a new verification challenge to your receiver, then restarts delivery. You can select Failed or Delivered deliveries to send again; select none to resume with new changes only.

Replay selected deliveries

On an Active webhook, select up to 100 Failed or Delivered deliveries and choose Replay selected deliveries. FieldTask verifies the receiver with a new challenge, then sends them again with their original event IDs and bodies. Each starts a new retry cycle of up to 12 attempts or 24 hours.

Only deliveries for events within the history period, for records the connection can still read, can be selected.

Limits

Resuming, replaying, staging a signing secret and activating it share a limit of 5 per webhook in each 15-minute window. Choose Disable webhook to stop a webhook permanently; its waiting deliveries are cancelled.

Rotate the signing secret

Rotate the secret if it may have been exposed, or on your own schedule. The webhook must be Active or Paused.

1. In Delivery details, choose Stage new signing secret, then Confirm. Copy the new secret; it's shown once. The current secret keeps signing deliveries.

2. Add the new secret to your receiver alongside the current one, for example FIELDTASK_WEBHOOK_SECRETS="whsec_CURRENT_PLACEHOLDER whsec_NEW_PLACEHOLDER". The samples above accept a request that verifies with either.

3. Within 15 minutes of staging, choose Activate signing secret, then Confirm. FieldTask sends a verification challenge signed only with the new secret, so your receiver must already have it. The staged secret's expiry is shown as Staged secret expires; after it, stage a new one.

4. After activation, the new secret signs every delivery. For 5 minutes, deliveries also carry a signature from the previous secret, so webhook-signature contains two values:

   webhook-signature: v1,SIGNATURE_WITH_NEW_SECRET v1,SIGNATURE_WITH_PREVIOUS_SECRET

   The end of this overlap is shown as Previous key signing ends.

5. After the overlap ends, remove the previous secret from your receiver.

• Staging again before activating replaces the staged secret.
• You can't stage another secret until the overlap has ended.
• This overlap only applies to webhook signing secrets. API token rotation works differently; see Authentication.