- Webhooks
- Event Types and Payloads
Webhooks
Event Types and Payloads
Catalog of the webhook event types, with the payload fields and examples of each event family.
This page lists every event type Remitian delivers to your webhook endpoint, grouped by family, with the fields of the data payload of each one. To subscribe to events and to learn about the event envelope, signature verification and retries, see Webhooks.
Every event tied to a firm carries a firm object right after id, with the same shape in every event family: firm.id is Remitian’s identifier for the firm and firm.externalId is your external identifier for the firm, set through the Public API when the firm is created or updated. firm.externalId is null when the firm has no external id. The firm object itself is null only when the firm could not be resolved for the event.
Test
| Event Type | Description |
|---|---|
webhook.Test.v1 | A test event delivered to verify your endpoint configuration. Sent only via the Send test event button — it cannot be subscribed to. It carries no firm object, since it is sent per integrator rather than per firm. |
Tax Payments (schedule.*)
| Event Type | Description |
|---|---|
schedule.PendingApproval.v1 | A tax payment is awaiting approval. |
schedule.QueuedForPayment.v1 | A tax payment has been queued for payment. |
schedule.Submitted.v1 | A tax payment has been submitted to the tax authority. |
schedule.Processed.v1 | A tax payment has been successfully processed. |
schedule.Failed.v1 | A tax payment has failed. |
schedule.Voided.v1 | A tax payment has been voided. |
schedule.Deleted.v1 | A tax payment has been deleted. |
schedule.Expired.v1 | A tax payment expired without being processed. |
schedule.PaidManually.v1 | A tax payment has been marked as paid manually, in the Remitian platform or through the API. See Mark a Tax Payment as Paid Manually. |
schedule.Denied.v1 | A tax payment has been denied. |
Payload:
The data field contains the tax payment:
| Field | Description |
|---|---|
id | Tax payment identifier |
firm.id | Firm the taxpayer belongs to |
firm.externalId | Your external identifier for the firm; null when the firm has none |
taxpayerId | Taxpayer the payment belongs to |
businessId | Business, when the payment is for a business tax entity |
externalId | Your external identifier for the tax payment, when provided at creation |
taxAccountId | Tax account the payment is made against |
bankAccountId | Funding bank account |
approverId | Firm user who approved the payment |
paymentTypeId | Payment type (see Available Payment Types) |
status | Payment status, one of the Tax Payment Statuses (e.g. PendingClientApproval, Processed) |
confirmationNumber | Confirmation number recorded when the payment was submitted through a portal, whether the tax authority’s own or a bank’s tax payment service. Set on schedule.Processed.v1 when one was recorded; null on every other event, and on schedule.Processed.v1 for payments remitted directly through the banking network |
currency / amount / fee | Monetary details |
periodEndDate, pullDate, submissionDate, remitDate, paymentDate | Payment lifecycle dates |
Tax Form Imports (taxFormParsingRequest.*)
| Event Type | Description |
|---|---|
taxFormParsingRequest.Processing.v1 | A tax form parsing request is being processed. |
taxFormParsingRequest.InReview.v1 | A tax form parsing request is under review. |
taxFormParsingRequest.Processed.v1 | A tax form parsing request has been processed. |
taxFormParsingRequest.Completed.v1 | A tax form parsing request has been completed. |
taxFormParsingRequest.Cancelled.v1 | A tax form parsing request has been cancelled. |
taxFormParsingRequest.Error.v1 | A tax form parsing request encountered an error. |
Payload:
The data field contains the parsing request:
| Field | Description |
|---|---|
id | Parsing request identifier |
firm.id | Firm the taxpayer belongs to |
firm.externalId | Your external identifier for the firm; null when the firm has none |
taxpayerId | Taxpayer the form belongs to |
status | Parsing request status |
taxFormType / taxFormId | The recognized tax form |
taxFormParsing | Extracted values (payments, tax entity, period end date, filing status, adjusted gross income), each with a confidence score |
errors | Parsing errors, if any |
paymentType | Payment type derived from the form |
Batches (batch.*)
| Event Type | Description |
|---|---|
batch.Processed.v1 | Every item of a batch has succeeded or failed. See Tax Payment Batches. |
Payload:
The data field contains the batch:
| Field | Description |
|---|---|
id | Batch identifier |
firm.id | Firm the batch belongs to |
firm.externalId | Your external identifier for the firm; null when the firm has none |
externalId | Your external identifier for the batch |
actionType | What the batch does (e.g. ScheduleCreation for a tax payment batch) |
totalItems | Number of items in the batch |
succeededItems | Number of items that succeeded |
failedItems | Number of items that failed |
SFTP File Delivery (outboundFile.*)
| Event Type | Description |
|---|---|
outboundFile.Published.v1 | An outbound file is published and ready to download over SFTP. Sent once per file. See the SFTP File Specification guide. |
Payload:
The data field contains the published file:
{
"id": "019a3b4c-5d6e-7f80-9a1b-2c3d4e5f6a7b",
"firm": {
"id": "019b1f0e-6a4c-7d21-9b3e-2c8f5a7d4e10",
"externalId": "FIRM-1042"
},
"fileType": "FirmDailyPaymentFile",
"path": "/outbound/2026-12-01/firms/019b1f0e-6a4c-7d21-9b3e-2c8f5a7d4e10/taxpayments_019b1f0e-6a4c-7d21-9b3e-2c8f5a7d4e10_2026-12-01.csv.pgp",
"fileDate": "2026-12-01"
}
| Field | Type | Description |
|---|---|---|
id | guid | Outbound file identifier |
firm.id | guid | Firm the file belongs to |
firm.externalId | string | Your external identifier for the firm; null when the firm has none |
fileType | string | Type of the file. FirmDailyPaymentFile for the daily payment file; more types may be added |
path | string | Full path of the file on the SFTP server, ready to download. See Path and Name of each file type in the SFTP File Specification guide |
fileDate | date | Date the file covers (yyyy-mm-dd) |
firm is null for file types that do not belong to one firm. The event is sent once per file. Use path (or id) to skip files you have already processed.
Tax Identity Verifications (taxIdentityVerification.*)
| Event Type | Description |
|---|---|
taxIdentityVerification.Created.v1 | A tax identity verification has been created. Sent once per verification, whether it was created through the Public API, the Remitian portal or the widget. |
taxIdentityVerification.Succeeded.v1 | A tax identity verification has succeeded. Sent when the tax authority confirms the identity, or when Remitian completes a manual review successfully. |
taxIdentityVerification.Failed.v1 | A tax identity verification has failed. Sent when the tax authority rejects the request and Remitian has no automatic retry left. |
These events let you follow a verification without polling. See Use Case 6: Manage Tax Identity Verifications.
Payload:
The data field contains the tax identity verification. It has the same fields as Get the Latest Verification in Use Case 6, plus the firm and taxpayer objects:
| Field | Type | Description |
|---|---|---|
id | guid | Tax identity verification identifier |
firm.id | guid | Firm the taxpayer belongs to |
firm.externalId | string | Your external identifier for the firm; null when the firm has none |
taxpayer.id | guid | Taxpayer the verification belongs to |
taxpayer.externalId | string | Your external identifier for the taxpayer; null when the taxpayer has none |
taxEntityId | guid | Tax entity verified |
type | string | Connection type used to create the verification, for example KentuckyBusiness. See the connection type catalog in Use Case 6 |
taxAuthority | string | Tax authority, for example US_KY |
taxEntityType | string | Type of the tax entity: IrsSsn (individual) or IrsEin (business) |
status | string | Status of the verification when the event was raised (see below) |
taxYear | number | Tax year the verification refers to |
requestedAt | datetime | When the verification was created (UTC) |
lastUpdatedAt | datetime | When the verification last changed (UTC) |
errors | string[] | Messages returned by the tax authority. Filled only on taxIdentityVerification.Failed.v1, otherwise empty |
Status by event type:
| Event Type | status values |
|---|---|
taxIdentityVerification.Created.v1 | Requested (submitted to the tax authority), PendingManualReview (Remitian reviews it before completing it) or Created (recorded, not yet submitted) |
taxIdentityVerification.Succeeded.v1 | Success |
taxIdentityVerification.Failed.v1 | Failed |
statusis a snapshot taken when the event was raised. The verification may have moved on by the time you receive the delivery, and events may arrive out of order.- Get the Latest Verification is the source of truth. Only the latest verification per tax authority is valid for a tax entity, so read it before acting on an event. It also reports the states that raise no event:
AwaitingConfirmation, andFailedMaxReachedwhen a failure was the last allowed attempt and new verifications for that tax authority are rejected. - Events are delivered for every verification of a taxpayer that belongs to the firm, whatever created it.
Example (taxIdentityVerification.Created.v1):
{
"id": "01a17881-9668-791a-aafa-02b706bd72af",
"eventType": "taxIdentityVerification.Created.v1",
"createdAtUtc": "2026-10-26T13:58:41Z",
"data": {
"id": "6f1c2d3e-8a4b-4c5d-9e6f-7a8b9c0d1e2f",
"firm": {
"id": "019b1f0e-6a4c-7d21-9b3e-2c8f5a7d4e10",
"externalId": "FIRM-1042"
},
"taxpayer": {
"id": "019bc3f4-d65e-73f7-8133-f5800e825509",
"externalId": "CLIENT-88231"
},
"taxEntityId": "049bc3f4-d65e-73f7-8133-f5800e825512",
"type": "KentuckyBusiness",
"taxAuthority": "US_KY",
"taxEntityType": "IrsEin",
"status": "Requested",
"taxYear": 2025,
"requestedAt": "2026-10-26T13:58:40Z",
"lastUpdatedAt": "2026-10-26T13:58:40Z",
"errors": []
}
}
Example (taxIdentityVerification.Succeeded.v1):
{
"id": "01a17887-8dc0-7703-a6d8-bc272a8b509e",
"eventType": "taxIdentityVerification.Succeeded.v1",
"createdAtUtc": "2026-10-26T14:05:12Z",
"data": {
"id": "6f1c2d3e-8a4b-4c5d-9e6f-7a8b9c0d1e2f",
"firm": {
"id": "019b1f0e-6a4c-7d21-9b3e-2c8f5a7d4e10",
"externalId": "FIRM-1042"
},
"taxpayer": {
"id": "019bc3f4-d65e-73f7-8133-f5800e825509",
"externalId": "CLIENT-88231"
},
"taxEntityId": "049bc3f4-d65e-73f7-8133-f5800e825512",
"type": "KentuckyBusiness",
"taxAuthority": "US_KY",
"taxEntityType": "IrsEin",
"status": "Success",
"taxYear": 2025,
"requestedAt": "2026-10-26T13:58:40Z",
"lastUpdatedAt": "2026-10-26T14:05:11Z",
"errors": []
}
}
Example (taxIdentityVerification.Failed.v1):
{
"id": "01a0f6ec-acc8-771e-908e-4945987c322d",
"eventType": "taxIdentityVerification.Failed.v1",
"createdAtUtc": "2026-10-01T10:05:01Z",
"data": {
"id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"firm": {
"id": "019b1f0e-6a4c-7d21-9b3e-2c8f5a7d4e10",
"externalId": "FIRM-1042"
},
"taxpayer": {
"id": "019bc3f4-d65e-73f7-8133-f5800e825509",
"externalId": "CLIENT-88231"
},
"taxEntityId": "049bc3f4-d65e-73f7-8133-f5800e825512",
"type": "KentuckyBusiness",
"taxAuthority": "US_KY",
"taxEntityType": "IrsEin",
"status": "Failed",
"taxYear": 2025,
"requestedAt": "2026-10-01T10:00:00Z",
"lastUpdatedAt": "2026-10-01T10:05:00Z",
"errors": [
"Account number does not match the authority records."
]
}
}