Webhooks are a way for fetchdocs to notify your app when certain events happen. This allows you to keep your app in sync with fetchdocs in near real-time.

Using webhooks, allows you to receive notifications when events occur in fetchdocs, without having to poll the fetchdocs API. This can help you to keep your app up-to-date with the latest information from fetchdocs and reduce the load.

⚠️ Webhook Retries

fetchdocs retries failed webhooks up to 5 times with an increasing delay between retries. If a webhook fails after 5 retries, it's considered failed and isn't retried again. It's important to ensure that your webhook endpoint is reliable and can handle the load of incoming requests. Note: alive webhooks are not retried.

📡 Supported events#

Currently, fetchdocs supports the following events:

• alive: Triggered periodically by fetchdocs to verify whether an identity still exists in your system.
• connection_status_changed: Triggered when the status of a connection changed.

🚀 Getting started#

To get started with webhooks, you need to provide a webhook URL to the fetchdocs support team. fetchdocs is calling this URL whenever an event occurs.

Each event includes a payload with information about the event. The payload is a JSON object in the body of the POST request and includes the following elements:

• event: The name of the event that occurred.
• payload: Additional data related to the event, depending on the event. Refer to the details below.
• identity: Information about the identity which relates to the webhook.
• timestamp: The timestamp when the event occurred.

fetchdocs expects your server to respond with a 200 OK status code to acknowledge that it received the event successfully. If fetchdocs doesn't receive a 200 OK status code, it logs that webhook as failed. fetchdocs isn't retrying failed webhooks.

⏱️ Avoid race conditions#

Sometimes it can happen that you receive a webhook before another webhook that fetchdocs sent even earlier. This can lead to wrong assumptions about the state of the system. To avoid this, it's recommended that you also store the timestamp of the last event you received and only process events that have a timestamp greater than the last event you received. Therefor the webhooks payload also includes the timestamp in ISO format including milliseconds.

📦 Payloads#

The payloads for each event are as follows:

Event "alive"#

fetchdocs periodically sends this webhook to verify whether an identity still exists in your system. This is part of an automated cleanup process for identities without connections that haven't communicated with fetchdocs in over a year.

Unlike other webhook events, the alive webhook requires a specific JSON response from your server — not just a 200 OK status code.

The payload includes:

• identity_uuid: The UUID of the identity being checked.
• identity_client_identifier: Your identifier for the identity.

Example:

Your server must respond with a JSON body containing an identity boolean value:

Response values#

• true means the identity still exists in your system.
• false means the identity no longer exists in your system. fetchdocs will eventually remove it after a confirmation period.

⚠️ Conservative handling

If the webhook fails, times out, or returns an unexpected response, fetchdocs assumes the identity still exists and will not remove it. Only an explicit false value triggers the cleanup process.

Event "connection_status_changed"#

fetchdocs triggers this event when the status of a connection changed. The payload includes the following elements:

• connection_uuid: The UUID of the connection that changed status.
• new_status: The new status of the connection. You should update your local status of the connection based on this value.

Example: