Docs menu: Webhooks

Webhooks

The events Tallio sends to your endpoints, each signed with the tallio-signature header.

On this page

The event object
Tallio accepted a document
The document was issued and has a MARK
The provider or AADE refused the document
Tallio could not deliver the document to the provider

The event object #

Sent by Tallio

Signature header

tallio-signaturestringrequired: t=<unix seconds>,v1=<signature>[,v1=…]. The signature is the lowercase hex HMAC-SHA256 of <t>.<raw body bytes>, keyed with the endpoint's full secret string (whsec_ included) as UTF-8. Use a constant-time comparison; any one of up to 8 v1 values may match (a secret rolling). Ignore elements you do not know. Reject a t more than 300 seconds away from now.
Show patternHide pattern
^t=\d+(?:,[a-z0-9]+=[^,\s]+)+$

Payload

idstringrequired

Id of the event (evt_…).

Show pattern

^evt_[0-9A-Za-z]{22}$

objectstringrequired

Always "event".

Always event

typestringrequired

What happened: document.created (Tallio accepted a document), document.issued (it has a MARK), document.rejected (the provider or AADE refused it), document.failed (Tallio could not deliver it).

One of: document.created, document.issued, document.rejected, document.failed

createdstringrequired

When the event happened.

Format: date-time

api_versionstringrequired

The API version data.object is rendered in, e.g. 0.1.0.

livemodebooleanrequired

True for an event from live mode, false for test mode.

dataobjectrequired

The object the event is about.

Show nested fields (2)

objectobjectrequired

The document as it was right after the event.

Show nested fields (21)

idstringrequired

Id of the document (doc_…).

Show pattern

^doc_[0-9A-Za-z]{22}$

objectstringrequired

Always "document".

Always document

merchantstringrequired

Id of the merchant (mer_…).

Show pattern

^mer_[0-9A-Za-z]{22}$

modestringrequired

live for a document created with a live key, test for a test key.

One of: live, test

providerstringrequired

The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document.

One of: sandbox, mydata, wrapp, impact, epsilon, softone, prosvasis

typestringrequired

AADE myDATA document type: 1.1 sales invoice, 2.1 service invoice, 5.1 credit note (associated), 5.2 credit note (non-associated), 11.1 retail sales receipt, 11.2 retail service receipt.

One of: 1.1, 2.1, 5.1, 5.2, 11.1, 11.2

statusstringrequired

Where the document stands: pending (Tallio accepted it; not yet issued, see stage), issued (has a MARK), rejected (the provider or AADE refused it), failed (Tallio could not deliver it to the provider).

One of: pending, issued, rejected, failed

stagestring | nullrequired

Where a pending document is (queued, submitting, awaiting_mark, reconciling); null unless status is pending.

One of: queued, submitting, awaiting_mark, reconciling

issue_datestringrequired

Issue date, YYYY-MM-DD.

Format: date

currencystringrequired

ISO 4217 currency. Only EUR for now.

Always EUR

netintegerrequired

Sum of the lines' net amounts, in minor units, at most 1000000000000000.

From 0 to 1000000000000000

vatintegerrequired

Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000.

From 0 to 1000000000000000

grossintegerrequired

net + vat, in minor units, at most 1250000000000000.

From 0 to 1250000000000000

markstring | nullrequired

MARK (AADE registration number) once issued, as a digit string; null before.

Show pattern

^[1-9]\d{0,18}$

uidstring | nullrequired

myDATA uid: the SHA-1 (40 upper-case hex digits) AADE derives from the document's identifiers; null until known.

Show pattern

^[0-9A-F]{40}$

qr_urlstring | nullrequired

URL the document's QR code points to; null until the provider returns one.

Format: uri

errorobject | nullrequired

Why the document was rejected or failed; null otherwise.

Show nested fields (6)

codestringrequired: Stable machine-readable error code. Branch on this, never on message.
One of: validation_failed, unauthorized, not_found, idempotency_conflict, idempotency_in_progress, payload_too_large, unsupported_media_type, rate_limited, not_supported, provider_rejected, provider_unavailable, internal_error
messagestringrequired: Human-readable explanation, safe to show to a developer.
provider_codestring | nullrequired: The provider's own error code, or null when the error did not come from a provider.
provider_messagestring | nullrequired: The provider's own error message, verbatim, or null when the error did not come from a provider.
retryablebooleanrequired: True when the same request may succeed if sent again later.
provider_rawany: The provider's error response body as received, or a TruncatedProviderRaw marker when it exceeds 4096 bytes of JSON. Never holds request headers, credentials or the request payload.

classificationobjectrequired

How the document was classified for myDATA.

Show nested fields (2)

sourcestringrequired: default when any line took Tallio's default, else override when any line took the merchant's override, else line.
One of: line, override, default
warningsstring[]required: What to check before issuing, e.g. that defaults were applied.

timelineobject[]required

The document's events, oldest first, at most 100.

Up to 100 items

Each item: One event in a document's history. GET /events/{id} returns the full Event.

Show nested fields (3)

idstringrequired: Id of the event (evt_…).
Show patternHide pattern
^evt_[0-9A-Za-z]{22}$
typestringrequired: What happened: document.created (Tallio accepted a document), document.issued (it has a MARK), document.rejected (the provider or AADE refused it), document.failed (Tallio could not deliver it).
One of: document.created, document.issued, document.rejected, document.failed
createdstringrequired: When the event happened.
Format: date-time

createdstringrequired

When Tallio accepted the document.

Format: date-time

updatedstringrequired

When the document last changed.

Format: date-time

previous_attributesobject

The values the changed fields had before the event; absent for an event that changed nothing.

Show nested fields (21)

idstring

Id of the document (doc_…).

Show pattern

^doc_[0-9A-Za-z]{22}$

objectstring

Always "document".

Always document

merchantstring

Id of the merchant (mer_…).

Show pattern

^mer_[0-9A-Za-z]{22}$

modestring

live for a document created with a live key, test for a test key.

One of: live, test

providerstring

The licensed e-invoicing provider (or direct myDATA, or Tallio's sandbox) that issues the document.

One of: sandbox, mydata, wrapp, impact, epsilon, softone, prosvasis

typestring

AADE myDATA document type: 1.1 sales invoice, 2.1 service invoice, 5.1 credit note (associated), 5.2 credit note (non-associated), 11.1 retail sales receipt, 11.2 retail service receipt.

One of: 1.1, 2.1, 5.1, 5.2, 11.1, 11.2

statusstring

One of: pending, issued, rejected, failed

stagestring | null

Where a pending document is (queued, submitting, awaiting_mark, reconciling); null unless status is pending.

One of: queued, submitting, awaiting_mark, reconciling

issue_datestring

Issue date, YYYY-MM-DD.

Format: date

currencystring

ISO 4217 currency. Only EUR for now.

Always EUR

netinteger

Sum of the lines' net amounts, in minor units, at most 1000000000000000.

From 0 to 1000000000000000

vatinteger

Sum of the lines' VAT, each line rounded half up to the minor unit, in minor units, at most 1000000000000000.

From 0 to 1000000000000000

grossinteger

net + vat, in minor units, at most 1250000000000000.

From 0 to 1250000000000000

markstring | null

MARK (AADE registration number) once issued, as a digit string; null before.

Show pattern

^[1-9]\d{0,18}$

uidstring | null

myDATA uid: the SHA-1 (40 upper-case hex digits) AADE derives from the document's identifiers; null until known.

Show pattern

^[0-9A-F]{40}$

qr_urlstring | null

URL the document's QR code points to; null until the provider returns one.

Format: uri

errorobject | null

Why the document was rejected or failed; null otherwise.

Show nested fields (6)

codestringrequired: Stable machine-readable error code. Branch on this, never on message.
One of: validation_failed, unauthorized, not_found, idempotency_conflict, idempotency_in_progress, payload_too_large, unsupported_media_type, rate_limited, not_supported, provider_rejected, provider_unavailable, internal_error
messagestringrequired: Human-readable explanation, safe to show to a developer.
provider_codestring | nullrequired: The provider's own error code, or null when the error did not come from a provider.
provider_messagestring | nullrequired: The provider's own error message, verbatim, or null when the error did not come from a provider.
retryablebooleanrequired: True when the same request may succeed if sent again later.
provider_rawany: The provider's error response body as received, or a TruncatedProviderRaw marker when it exceeds 4096 bytes of JSON. Never holds request headers, credentials or the request payload.

classificationobject

How the document was classified for myDATA.

Show nested fields (2)

sourcestringrequired: default when any line took Tallio's default, else override when any line took the merchant's override, else line.
One of: line, override, default
warningsstring[]required: What to check before issuing, e.g. that defaults were applied.

timelineobject[]

The document's events, oldest first, at most 100.

Up to 100 items

Each item: One event in a document's history. GET /events/{id} returns the full Event.

Show nested fields (3)

idstringrequired: Id of the event (evt_…).
Show patternHide pattern
^evt_[0-9A-Za-z]{22}$
typestringrequired: What happened: document.created (Tallio accepted a document), document.issued (it has a MARK), document.rejected (the provider or AADE refused it), document.failed (Tallio could not deliver it).
One of: document.created, document.issued, document.rejected, document.failed
createdstringrequired: When the event happened.
Format: date-time

createdstring

When Tallio accepted the document.

Format: date-time

updatedstring

When the document last changed.

Format: date-time

requestobject | nullrequired

The API call that caused the event; null when Tallio caused it, e.g. issuing in the background.

Show nested fields (2)

idstringrequired: Request id (the x-request-id response header) of the API call that caused it.
Show patternHide pattern
^(?:req_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|client:[A-Za-z0-9._:-]{8,128}|[A-Za-z0-9._-]{1,16}::[A-Za-z0-9._:-]{6,110})$
idempotency_keystring | nullrequired: The Idempotency-Key that call sent, or null.
1 to 255 characters
Show patternHide pattern
^[\x21-\x7E]+$

Responses
Status	Description
`2XX`	Received.

Tallio accepted a document #

Event document.created

Example payload

{
  "id": "evt_02y9O8rhJ2Z2v1fOH2XiSH",
  "object": "event",
  "type": "document.created",
  "created": "2026-10-11T09:30:00.000Z",
  "api_version": "0.1.0",
  "livemode": false,
  "data": {
    "object": {
      "id": "doc_02y9O8rhJKVUXRvojdffcz",
      "object": "document",
      "merchant": "mer_02y9O8rh7F50tGi0QcWRrx",
      "mode": "test",
      "provider": "sandbox",
      "type": "1.1",
      "status": "pending",
      "stage": "queued",
      "issue_date": "2026-10-10",
      "currency": "EUR",
      "net": 2500,
      "vat": 435,
      "gross": 2935,
      "mark": null,
      "uid": null,
      "qr_url": null,
      "error": null,
      "classification": {
        "source": "default",
        "warnings": [
          "No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."
        ]
      },
      "timeline": [
        {
          "id": "evt_02y9O8rhJ2Z2v1fOH2XiSH",
          "type": "document.created",
          "created": "2026-10-11T09:30:00.000Z"
        }
      ],
      "created": "2026-10-11T09:30:00.000Z",
      "updated": "2026-10-11T09:30:00.000Z"
    }
  },
  "request": {
    "id": "req_0192f4c1-7a40-7c42-9b1d-4e5f6a7b8c9d",
    "idempotency_key": "order-1042"
  }
}

The document was issued and has a MARK #

Event document.issued

Example payload

{
  "id": "evt_02y9O8s1a8ymJqpmAy0nLe",
  "object": "event",
  "type": "document.issued",
  "created": "2026-10-11T09:30:02.000Z",
  "api_version": "0.1.0",
  "livemode": false,
  "data": {
    "object": {
      "id": "doc_02y9O8rhJKVUXRvojdffcz",
      "object": "document",
      "merchant": "mer_02y9O8rh7F50tGi0QcWRrx",
      "mode": "test",
      "provider": "sandbox",
      "type": "1.1",
      "status": "issued",
      "stage": null,
      "issue_date": "2026-10-10",
      "currency": "EUR",
      "net": 2500,
      "vat": 435,
      "gross": 2935,
      "mark": "900000000000001",
      "uid": "4E1F0A6C2B9D8E7F6A5B4C3D2E1F0A9B8C7D6E5F",
      "qr_url": "https://sandbox.tallio.invalid/qr/900000000000001",
      "error": null,
      "classification": {
        "source": "default",
        "warnings": [
          "No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."
        ]
      },
      "timeline": [
        {
          "id": "evt_02y9O8rhJ2Z2v1fOH2XiSH",
          "type": "document.created",
          "created": "2026-10-11T09:30:00.000Z"
        },
        {
          "id": "evt_02y9O8s1a8ymJqpmAy0nLe",
          "type": "document.issued",
          "created": "2026-10-11T09:30:02.000Z"
        }
      ],
      "created": "2026-10-11T09:30:00.000Z",
      "updated": "2026-10-11T09:30:02.000Z"
    },
    "previous_attributes": {
      "status": "pending",
      "stage": "awaiting_mark",
      "mark": null,
      "uid": null,
      "qr_url": null,
      "timeline": [
        {
          "id": "evt_02y9O8rhJ2Z2v1fOH2XiSH",
          "type": "document.created",
          "created": "2026-10-11T09:30:00.000Z"
        }
      ],
      "updated": "2026-10-11T09:30:00.000Z"
    }
  },
  "request": null
}

The provider or AADE refused the document #

Event document.rejected

Example payload

{
  "id": "evt_02y9O8s1a8ymJqpmAy0nLf",
  "object": "event",
  "type": "document.rejected",
  "created": "2026-10-11T09:30:02.000Z",
  "api_version": "0.1.0",
  "livemode": false,
  "data": {
    "object": {
      "id": "doc_02y9O8rhJKVUXRvojdffcz",
      "object": "document",
      "merchant": "mer_02y9O8rh7F50tGi0QcWRrx",
      "mode": "test",
      "provider": "sandbox",
      "type": "1.1",
      "status": "rejected",
      "stage": null,
      "issue_date": "2026-10-10",
      "currency": "EUR",
      "net": 2500,
      "vat": 435,
      "gross": 2935,
      "mark": null,
      "uid": null,
      "qr_url": null,
      "error": {
        "code": "provider_rejected",
        "message": "The provider rejected the document.",
        "provider_code": "228",
        "provider_message": "Invalid counterpart VAT number.",
        "retryable": false
      },
      "classification": {
        "source": "default",
        "warnings": [
          "No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."
        ]
      },
      "timeline": [
        {
          "id": "evt_02y9O8rhJ2Z2v1fOH2XiSH",
          "type": "document.created",
          "created": "2026-10-11T09:30:00.000Z"
        },
        {
          "id": "evt_02y9O8s1a8ymJqpmAy0nLf",
          "type": "document.rejected",
          "created": "2026-10-11T09:30:02.000Z"
        }
      ],
      "created": "2026-10-11T09:30:00.000Z",
      "updated": "2026-10-11T09:30:02.000Z"
    },
    "previous_attributes": {
      "status": "pending",
      "stage": "awaiting_mark",
      "error": null,
      "timeline": [
        {
          "id": "evt_02y9O8rhJ2Z2v1fOH2XiSH",
          "type": "document.created",
          "created": "2026-10-11T09:30:00.000Z"
        }
      ],
      "updated": "2026-10-11T09:30:00.000Z"
    }
  },
  "request": null
}

Tallio could not deliver the document to the provider #

Event document.failed

Example payload

{
  "id": "evt_02y9O8s1a8ymJqpmAy0nLg",
  "object": "event",
  "type": "document.failed",
  "created": "2026-10-11T09:30:02.000Z",
  "api_version": "0.1.0",
  "livemode": false,
  "data": {
    "object": {
      "id": "doc_02y9O8rhJKVUXRvojdffcz",
      "object": "document",
      "merchant": "mer_02y9O8rh7F50tGi0QcWRrx",
      "mode": "test",
      "provider": "sandbox",
      "type": "1.1",
      "status": "failed",
      "stage": null,
      "issue_date": "2026-10-10",
      "currency": "EUR",
      "net": 2500,
      "vat": 435,
      "gross": 2935,
      "mark": null,
      "uid": null,
      "qr_url": null,
      "error": {
        "code": "provider_unavailable",
        "message": "The provider is temporarily unavailable.",
        "provider_code": null,
        "provider_message": null,
        "retryable": true
      },
      "classification": {
        "source": "default",
        "warnings": [
          "No income classification on line 2; applied the 1.1 default category1_1/E3_561_001. Set it on the line, or as a merchant override, if that is wrong."
        ]
      },
      "timeline": [
        {
          "id": "evt_02y9O8rhJ2Z2v1fOH2XiSH",
          "type": "document.created",
          "created": "2026-10-11T09:30:00.000Z"
        },
        {
          "id": "evt_02y9O8s1a8ymJqpmAy0nLg",
          "type": "document.failed",
          "created": "2026-10-11T09:30:02.000Z"
        }
      ],
      "created": "2026-10-11T09:30:00.000Z",
      "updated": "2026-10-11T09:30:02.000Z"
    },
    "previous_attributes": {
      "status": "pending",
      "stage": "submitting",
      "error": null,
      "timeline": [
        {
          "id": "evt_02y9O8rhJ2Z2v1fOH2XiSH",
          "type": "document.created",
          "created": "2026-10-11T09:30:00.000Z"
        }
      ],
      "updated": "2026-10-11T09:30:00.000Z"
    }
  },
  "request": null
}