Webhooks and delivery log — send farm events

Farm portal → Manage → Webhooks sends selected farm events to an HTTPS endpoint that your organisation controls. Use it when another system needs to react to an animal or alert change without repeatedly polling Farmlync. This configuration belongs to the selected farm. A Farm Owner or Manager can create and remove endpoints and rotate secrets; other permitted viewers can inspect the lists. The Webhooks module must be enabled for the organisation. If no farm is selected, select one first.

Add an endpoint

Select Add endpoint. It is unavailable until the event-type catalogue loads. Complete the dialog:

Control	Enter or choose
Endpoint URL	An absolute https:// URL for your receiving service, up to 2,048 characters. Farmlync rejects private, loopback and other unsafe destinations.
Events to send	Check at least one event. The choices come from Farmlync’s event catalogue. * subscribes to every current and future event type; choose specific events if the receiver needs a smaller scope.
Description (optional)	A short purpose or receiver name, up to 500 characters.

Select Create to save, or Cancel to leave without creating it. Validation and server errors appear in the dialog. The current catalogue includes animal registration, exit, exit reversal, deletion and status changes, plus alert creation and status changes. The available choices are shown in the form and may grow as Farmlync adds event forwarding.

After creation, copy the signing secret from the reveal dialog immediately. It is shown once and cannot be retrieved later. Store it in your receiving system’s secure configuration. Farmlync protects configured secrets at rest outside ordinary development, but your receiver still has to protect its copy.

Every delivery is a JSON POST with these verification headers:

Header	Receiver use
X-Farmlync-Signature	Compare this with sha256= plus the lowercase HMAC-SHA256 of {timestamp}.{exact request body}, using the signing secret. Use a constant-time comparison.
X-Farmlync-Timestamp	Unix timestamp included in the signed value. Reject requests outside your chosen clock-skew window to reduce replay risk.
X-Farmlync-Event	The event type, such as animal.registered. Route the verified payload by this value.
X-Farmlync-Delivery	Stable delivery ID. Store it as a deduplication key because retries can deliver the same event more than once.

Verify the signature against the raw body before parsing or reformatting it, then validate the event and payload your application accepts. Return a 2xx response only after your receiver has durably accepted the event. Redirect responses are not followed and count as failures.

If you lose the secret, use Rotate secret, copy the new value and update the receiver. Rotation replaces the old secret immediately; there is no overlap period. Coordinate the change to avoid failed verification at your endpoint. Do not put the secret in an issue, email or ordinary application log.

Review or remove an endpoint

The endpoint table shows Endpoint URL and optional description, Events, Status, Created date and Actions. It shows 25 rows per client-side page. Rotate secret generates a new one-time secret. Delete opens a confirmation; confirming removes the endpoint, stops new deliveries and causes already queued deliveries to be cancelled when the worker next processes them. Deletion cannot be undone. There is no edit, enable/disable or test-send control on this page. To change a URL or event selection, create a replacement endpoint, configure its receiver and remove the old endpoint when ready.

Check deliveries

Select Delivery log from the Webhooks page. The Status selector filters to All statuses, Pending, Delivered, Failed or Dead-lettered. A delivery cancelled because its endpoint was removed can appear under All statuses, but the current selector has no Cancelled filter. The page requests up to 200 newest matching deliveries for the selected farm and displays 25 per client-side table page; changing the status makes a separate latest-200 request. It is not an unlimited archive.

Column	Meaning
Event	Event type sent to the subscribed endpoint.
Status	Current delivery state. Pending is waiting to run, Delivered received a 2xx, Failed had an unsuccessful attempt and is scheduled to retry, DeadLettered exhausted its retry window, and Cancelled was intentionally not sent because its endpoint no longer existed or was inactive.
Attempts	Attempts made out of the configured maximum.
Last result	HTTP response code if recorded, otherwise the last error or a dash. Hover over a shortened error to read its full text.
Created	When the delivery was created, displayed in the farm’s date/time format.
Actions	Redeliver for Failed or DeadLettered rows, shown to Owners and Managers.

Redeliver puts the same Failed or DeadLettered delivery back into the Pending queue with a fresh attempt window; it does not mean the receiver has accepted it. Recheck the log after processing. Your receiving system must tolerate duplicate events because retries and re-queues can send an event more than once. If nothing appears, confirm the selected farm, the endpoint’s event subscriptions and whether the relevant event actually occurred. A page that says there are no endpoints or deliveries should represent a successful empty request; the current UI can also show that state when its read request fails, which is recorded as a product gap for correction.

Retry and retention behaviour

Farmlync checks for due deliveries on a timer, claims a bounded batch and sends outside the database lock. The default configuration permits six attempts. Failed attempts use exponential delays starting at about 5 seconds and cap each delay at 10 minutes. The exact values are deployment settings and can differ by environment.

Delivery is at least once. A network failure after the receiver accepted a request can still lead to a retry, so X-Farmlync-Delivery deduplication is required even when the receiver normally responds quickly. Farmlync retains delivery evidence for investigation, but this page exposes only the newest bounded result. Delivered rows have an automated retention path; retention for other terminal states is recorded as a product gap and must not be treated as an indefinite audit guarantee.