Skip to main content

Return requested external data

When a user requests fresh external data in Krebit Finance, your integration receives an act.fetch_data webhook. Fetch the selected values from your source, then return them through the act data API. Krebit fetches built-in provider fields itself.

Register before a refresh​

Register an act.fetch_data webhook with an HTTPS target and store its secret. The registration must be active and belong to a user with access to the act. Complete authentication and use KREBIT_API and ACCESS_TOKEN from the quickstart.

curl --fail-with-body --silent --show-error --request POST \
  "${KREBIT_API}/webhooks" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"event":"act.fetch_data","target":"https://yourapp.example.com/webhooks/krebit"}'

A user selects fields to refresh in Krebit Finance. The webhook is sent when that selection includes external fields. An eligible registration is required before users can request these refreshes.

Read the request​

Verify the signature, durably record or enqueue the request, and return 2xx promptly. Acknowledging delivery does not complete the fetch; submit results separately through the API.

This excerpt shows the identifiers and one selected external field:

{
  "id": "4be08bac-7e3c-4615-a018-cd47c3d403ad",
  "event": "act.fetch_data",
  "data": {
    "request_id": "ab102a75-2f1b-4a4b-9e5f-873d9a740d92",
    "requested_at": "2026-10-11T10:00:00Z",
    "expires_at": "2026-10-11T10:30:00Z",
    "act": {"uuid": "123e4567-e89b-12d3-a456-426614174000"},
    "fields": [
      {
        "id": 100,
        "template_field_id": 42,
        "template_field_key": "companyName",
        "template_field_name": "Company name",
        "type": "text",
        "external_data_field": true,
        "source": "external_data",
        "options": null
      }
    ]
  }
}
  • id identifies a webhook event. Use it to deduplicate deliveries.
  • data.request_id identifies the fetch request and is shared across destinations and retries. Return it as fetch_request_id and track completion per request and field.
  • data.expires_at is the deadline for returning results. The default processing window is 30 minutes, including queue and delivery time; use the supplied deadline.
  • data.act.uuid identifies the act to update.
  • data.fields contains the entire selected set, including built-in fields. Process only entries where external_data_field is true.

The fields are a snapshot of the act definitions when the refresh was requested, rather than fetched results. Match fields by their act data-point id, or by template IDs or keys. Names are descriptive labels. Use type and options to format values; structured fields include their effective columns. Do not infer definitions from a live template that may have changed.

See the event reference for the full act and field schemas.

Return a value​

Use an API bearer token with permission to update the act. The webhook secret verifies deliveries; it does not authenticate API updates. Set these variables from the received request:

export ACT_UUID="123e4567-e89b-12d3-a456-426614174000"
export FETCH_REQUEST_ID="ab102a75-2f1b-4a4b-9e5f-873d9a740d92"
export DATA_ID=100

curl --fail-with-body --silent --show-error --request PUT \
  "${KREBIT_API}/acts/${ACT_UUID}/data/${DATA_ID}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data "{\"fetch_request_id\":\"${FETCH_REQUEST_ID}\",\"value\":\"Example AB\"}"

Send value as a string in the format accepted by the field type. For structured data, the string contains the serialized JSON value. A successful response updates both the current value and its stored source value and records the refresh in the act history.

Return several values or a failure​

The bulk endpoint accepts a subset of the selected external fields. Put fetch_request_id at the top level; it applies to every item. Prefer each field's act data-point id; template_field_id and template_field_key are also supported.

PUT /api/1.0/acts/{act_uuid}/data
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
  "fetch_request_id": "ab102a75-2f1b-4a4b-9e5f-873d9a740d92",
  "data": [
    {"id": 100, "value": "Example AB"},
    {"id": 101, "error": "The external source is temporarily unavailable."}
  ]
}

Replace the example IDs with selected external fields from your request. Send exactly one of value or error for each item. An error is a string of up to 1,000 characters and requires fetch_request_id, including on the single-field endpoint. Reporting a failure ends that field's fetch without overwriting its previous value. Keep secrets and sensitive source responses out of error messages.

Retries and conflicts​

An identical completed value can be submitted again with the same request and field IDs. Identical reported errors can also be retried. Track these results so a redelivered webhook resumes unfinished work.

A 409 means a field is no longer awaiting that response, has changed since the request, or the request has expired. A result that differs from one already accepted also conflicts. Access and act editability are checked when results are submitted.

Correlated bulk results are validated together. If any item conflicts, no submitted values are applied. Inspect the error, reconcile the affected fields, and retry only the unresolved subset that remains eligible before the deadline. Do not remove fetch_request_id to bypass a conflict: that would turn a stale refresh into an ordinary update.

Invalid field values, duplicate items, or fields outside the selected external set return 422. Correct the payload before retrying. For an expired or conflicting field, ask the user to start a new refresh when appropriate.

API reference​