Guides

Spidr Webhooks

Spidr Webhooks

This document provides comprehensive information about all webhook types in the Spidr Unified API. Each webhook is triggered when specific actions are successfully completed via the Unified API, SST (Spidr Service Tool), or underlying provider.

📘

To see a complete list of all Spidr webhook fields and their descriptions, please reference: Webhook Field Index

Table of Contents

User Webhooks

user.edit

Description: The user.edit webhook contains details about changes that were made to a user or entity. It will provide both the new and old values for any fields that were changed. User details can be updated via API or SST. When customData is supplied to an edit request, it is also included as a top-level webhook field; a null value indicates that the field was cleared.

Triggers:

  • Successful API call to the Edit User endpoint (PATCH /v1/user/{id})
  • Successful API call to the Edit Entity endpoint (PATCH /v1/entity/{id})
  • Successful API call to the Edit ID Number endpoint (PATCH /v1/user/{id}/editIdNumber)
  • Successful API call to the Update User CIP Status endpoint (PATCH /v1/user/{id}/cipStatus)
  • User details updated via the appropriate SST role. If updated via SST, the sstRequestorUserId and sstRequestorUserEmail of the user who performed the update will be included in the actionRequestor object.

Example Payload:

{
  "uuid": "af21333c-b08d-4f1c-881a-df24707ab0e8",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "d082ef13f90e844780de5c2c66d6403b",
  "responseBody": {
    "updated": true,
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "user.edit",
  "customData": "customer-reference-123",
  "actionRequestor": {
    "source": "api"
  },
  "changes": [
    {
      "field": "firstName",
      "oldValue": "John",
      "newValue": "Jane"
    },
    {
      "field": "dateOfBirth",
      "oldValue": "1992-03-25T00:00:00.000Z",
      "newValue": "1991-03-25T00:00:00.000Z"
    },
    {
      "field": "email",
      "oldValue": "[email protected]",
      "newValue": "[email protected]"
    },
    {
      "field": "address.address1",
      "oldValue": "123 Evergreen St",
      "newValue": "100 Test St"
    },
    {
      "field": "customData",
      "oldValue": "previous-reference",
      "newValue": "customer-reference-123"
    }
  ]
}

user.create

Description: The user.create webhook is sent when a new user is successfully created in the system. It includes the user ID, product ID, CIP status, optional ZTM (Zero Touch Monitoring) data if applicable, and customData when it was supplied in the create request.

Triggers:

  • Successful API call to the Create User endpoint (POST /v1/user/create)

Example Payload:

{
  "uuid": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "e193fg24g01f955891ef6d3d77e7514c",
  "responseBody": {
    "id": "68950761e754b589d02d133c",
    "cip": {
      "status": "pass",
      "details": {}
    },
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "userId": "68950761e754b589d02d133c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "user.create",
  "customData": "customer-reference-123",
  "actionRequestor": {
    "source": "api"
  }
}

entity.create

Description: The entity.create webhook is sent when a new entity is successfully created in the system. It includes the entity ID, entity name, product ID, CIP status, optional ZTM data if applicable, and customData when it was supplied in the create request.

Triggers:

  • Successful API call to the Create Entity endpoint (POST /v1/entity/create)

Example Payload:

{
  "uuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "f284gh35h12g066902fg7e4e88f8625d",
  "responseBody": {
    "id": "68950761e754b589d02d144d",
    "cip": {
      "status": "pass",
      "details": {}
    },
    "spidrActionId": "68950786e754b589d01d144a"
  },
  "spidrActionId": "68950786e754b589d01d144a",
  "userId": "68950761e754b589d02d144d",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "entity.create",
  "customData": "customer-reference-123",
  "actionRequestor": {
    "source": "api"
  },
  "entityName": "Test Corporation LLC"
}

user.archive

Description: The user.archive webhook is sent when a user is successfully archived. It includes details about the changes made (such as the archive status and date) and the reason for archiving.

Triggers:

  • Successful API call to the Archive User endpoint (PATCH /v1/user/{id}/archiveUser)
  • User archived via the appropriate SST role

Example Payload:

{
  "uuid": "c2d3e4f5-g6h7-4i8j-9k0l-1m2n3o4p5q6r",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "f204gh35h12g066902fg7e4e88f8625d",
  "responseBody": {
    "updated": true,
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "user.archive",
  "actionRequestor": {
    "source": "api"
  },
  "archiveReason": "Account closure requested by user",
  "changes": [
    {
      "field": "isArchived",
      "oldValue": false,
      "newValue": true
    },
    {
      "field": "dateArchived",
      "oldValue": null,
      "newValue": "2025-10-23T15:30:00.000Z"
    }
  ]
}

user.retrieveId

Description: The user.retrieveId webhook is sent when a user's ID number is retrieved. This is an audit trail webhook that tracks when sensitive user information is accessed.

Triggers:

  • Successful API call to the Retrieve ID Number endpoint (GET /v1/user/{id}/retrieveIdNumber)
  • ID number retrieved via the appropriate SST role

Example Payload:

{
  "uuid": "d3e4f5g6-h7i8-4j9k-0l1m-2n3o4p5q6r7s",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "g315hi46i23h177013gh8f5f99g9736e",
  "spidrActionId": "68950786e754b589d01d1339",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "user.retrieveId",
  "actionRequestor": {
    "source": "api"
  }
}

user.retrieveIdHistory

Description: The user.retrieveIdHistory webhook is sent when a user's ID update history is retrieved. This is an audit trail webhook that tracks when sensitive user information history is accessed.

Triggers:

  • Successful API call to the Retrieve ID Number History endpoint (GET /v1/user/{id}/retrieveIdUpdateHistory)
  • ID update history retrieved via the appropriate SST role

Example Payload:

{
  "uuid": "e4f5g6h7-i8j9-4k0l-1m2n-3o4p5q6r7s8t",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "h426ij57j34i288124hi9g6g00h0847f",
  "spidrActionId": "68950786e754b589d01d1339",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "user.retrieveIdHistory",
  "actionRequestor": {
    "source": "api"
  }
}

Account Webhooks

account.create

Description: The account.create webhook is sent when a new account is successfully created for a user. It includes the account ID, user ID, product ID, and optional ZTM data.

Triggers:

  • Successful API call to the Create Account endpoint (POST /v1/account/create)

Example Payload:

{
  "uuid": "f5g6h7i8-j9k0-4l1m-2n3o-4p5q6r7s8t9u",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "i537jk68k45j399235ij0h7h11i1958g",
  "responseBody": {
    "accountId": "68950897f865c690e12e244a",
    "accountNumber": "123456789",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "account.create",
  "actionRequestor": {
    "source": "api"
  }
}

account.shippingAddressUpdate

Description: The account.shippingAddressUpdate webhook is sent when an account's shipping address is updated. It provides both the old and new values for any address fields that were changed.

Triggers:

  • Successful API call to the Edit Account endpoint (PATCH /v1/account/{id}) with shipping address data
  • Account shipping address updated via the appropriate SST role

Example Payload:

{
  "uuid": "g6h7i8j9-k0l1-4m2n-3o4p-5q6r7s8t9u0v",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "j648kl79l56k400346jk1i8i22j2069h",
  "responseBody": {
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "account.shippingAddressUpdate",
  "actionRequestor": {
    "source": "api"
  },
  "changes": [
    {
      "field": "shippingAddress.address1",
      "oldValue": "123 Main St",
      "newValue": "456 Oak Ave"
    },
    {
      "field": "shippingAddress.city",
      "oldValue": "San Francisco",
      "newValue": "Los Angeles"
    },
    {
      "field": "shippingAddress.state",
      "oldValue": "CA",
      "newValue": "CA"
    },
    {
      "field": "shippingAddress.postalCode",
      "oldValue": "94102",
      "newValue": "90001"
    }
  ]
}

account.statusUpdate

Description: The account.statusUpdate webhook is sent when an account's status is updated (e.g., from active to closed). It includes the old and new status values and optional status reason.

Triggers:

  • Successful API call to the Edit Account endpoint (PATCH /v1/account/{id}) with status data
  • Account status updated via the appropriate SST role

Example Payload:

{
  "uuid": "h7i8j9k0-l1m2-4n3o-4p5q-6r7s8t9u0v1w",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "k759lm80m67l511457kl2j9j33k3170i",
  "responseBody": {
    "newStatus": "closed",
    "statusReason": "customer_request",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "account.statusUpdate",
  "actionRequestor": {
    "source": "sst",
    "sstRequestorUserId": "admin123",
    "sstRequestorUserEmail": "[email protected]"
  },
  "changes": [
    {
      "field": "status",
      "oldValue": "active",
      "newValue": "closed"
    },
    {
      "field": "statusReason",
      "oldValue": null,
      "newValue": "customer_request"
    }
  ]
}

account.featureUpdate

Description: The account.featureUpdate webhook is sent when an account feature is enabled or disabled (e.g., international transactions, overdraft). It includes the change history showing which features were modified.

Triggers:

  • Successful API call to the Edit Account Features endpoint (PATCH /v1/account/{id}/editAccountFeatures)
  • Account features updated via the appropriate SST role

Example Payload:

{
  "uuid": "i8j9k0l1-m2n3-4o4p-5q6r-7s8t9u0v1w2x",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "l860mn91n78m622568lm3k0k44l4281j",
  "responseBody": {
    "updated": true,
    "accountId": "68950897f865c690e12e244a",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "account.featureUpdate",
  "actionRequestor": {
    "source": "api"
  },
  "changes": [
    {
      "field": "features.allow_international_transactions",
      "oldValue": true,
      "newValue": false
    }
  ]
}

account.pinChangeStageSuccess

Description: The account.pinChangeStageSuccess webhook is sent when a PIN change has been successfully staged with the processor. This occurs after the user submits their new PIN via the processor's PIN change URL but before the PIN change is committed via the API.

Triggers:

  • Processor (e.g., Galileo) sends an agserv_PIN_change_success event when the user successfully sets their PIN via the processor's PIN URL

Example Payload:

{
  "uuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "webhookType": "account.pinChangeStageSuccess",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "1234",
      "timestamp": "2025-10-23 10:15:00 MST",
      "type": "agserv_PIN_change_success",
      "balance_id": "5678",
      "msg_event_id": "98765",
      "eventType": "AccountEvent"
    },
    "accountNumber": "594100012345",
    "timestamp": "2025-10-23T17:15:00.000Z"
  }
}

account.pinChangeStageFail

Description: The account.pinChangeStageFail webhook is sent when a PIN change staging attempt fails at the processor. This uses the same payload shape as account.pinChangeStageSuccess — the webhookType string and the type field in providerDetails are the only differences.

Triggers:

  • Processor (e.g., Galileo) sends an agserv_PIN_change_fail event when the user's PIN change attempt fails (e.g., mismatched PINs, expired token, inactive account)

Example Payload:

{
  "uuid": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
  "webhookType": "account.pinChangeStageFail",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "1234",
      "timestamp": "2025-10-23 10:15:00 MST",
      "type": "agserv_PIN_change_fail",
      "balance_id": "5678",
      "msg_event_id": "98766",
      "eventType": "AccountEvent"
    },
    "accountNumber": "594100012345",
    "timestamp": "2025-10-23T17:15:00.000Z"
  }
}

account.pinChange

Description: The account.pinChange webhook is sent when a PIN change is confirmed by the underlying processor. This is an asynchronous confirmation from the processor that the PIN has been successfully changed in their system.

Triggers:

  • Processor (e.g., Galileo) sends a system_pin_change event after a PIN change is finalized

Example Payload:

{
  "uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "webhookType": "account.pinChange",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "1234",
      "timestamp": "2025-10-23 10:20:00 MST",
      "type": "system_pin_change",
      "balance_id": "5678",
      "cad": "9876",
      "eventType": "AccountEvent"
    },
    "accountNumber": "594100012345",
    "cardId": "68950ab9h087e812g34g466c",
    "timestamp": "2025-10-23T17:20:00.000Z"
  }
}
📘

Note: This webhook is different from card.pinChanged. The card.pinChanged webhook is sent immediately when you call the /commitPinChange endpoint, while account.pinChange is an asynchronous confirmation from the processor.

account.disputeCreated

Description: The account.disputeCreated webhook is sent when a dispute is created at the provider level. It includes the dispute ID, case number, dispute amount, and provider details.

Triggers:

  • Provider (e.g., Galileo) sends a dispute_created event when a new dispute is filed

Example Payload:

{
  "uuid": "d4e5f6g7-h8i9-4j0k-1l2m-3n4o5p6q7r8s",
  "webhookType": "account.disputeCreated",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "accountNumber": "594100012345",
    "caseNo": "CASE-2026-001234",
    "disputeId": "DSP-56789",
    "disputeAmount": "150.00",
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "3391",
      "timestamp": "2026-01-15 09:30:00 MST",
      "type": "dispute_created",
      "case_no": "CASE-2026-001234",
      "dispute_id": "DSP-56789",
      "dispute_amount": "150.00",
      "balance_id": "5678",
      "eventType": "AccountEvent"
    },
    "timestamp": "2026-01-15T16:30:00.000Z"
  }
}

account.balanceInquiry

Description: The account.balanceInquiry webhook is a provider-originated event sent when the processor reports a balance inquiry on an account (for example, an ATM or network balance check). It carries the current balance and the raw provider event in data.providerDetails.

Triggers:

  • Processor (e.g., Galileo) sends a bal event

Example Payload:

{
  "uuid": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "webhookType": "account.balanceInquiry",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "3391",
      "timestamp": "2026-01-15 03:23:10 MST",
      "type": "bal",
      "balance_id": "5678",
      "cad": "9876",
      "msg_event_id": "733151",
      "open_to_buy": "100.00",
      "eventType": "AccountEvent"
    },
    "accountNumber": "594100012345",
    "cardId": "68950ab9h087e812g34g466c",
    "balance": "100.00",
    "timestamp": "2026-01-15T10:23:10.000Z"
  }
}

account.statusChange

Description: The account.statusChange webhook is a provider-originated account status change reported by the processor. This is distinct from account.statusUpdate, which is generated when an account status is changed via the Unified API or SST. data.oldStatus and data.newStatus carry the processor status codes, and data.affectedAccountIds lists every account updated as a result of the change (for secured-credit account groups, a status change can cascade to related accounts).

Triggers:

  • Processor (e.g., Galileo) sends an account_status_change event

Example Payload:

{
  "uuid": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f",
  "webhookType": "account.statusChange",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "accountNumber": "594100012345",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "oldStatus": "N",
    "newStatus": "C",
    "affectedAccountIds": ["68950897f865c690e12e244a"],
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "3391",
      "timestamp": "2026-01-15 10:15:00 MST",
      "type": "account_status_change",
      "old_status": "N",
      "new_status": "C",
      "balance_id": "5678",
      "eventType": "AccountEvent"
    }
  }
}
📘

When the account belongs to a secured-credit group, data.securedCredit is included with role, groupAnchorAccountId, collateralAccountId, and directParentAccountId (when applicable).

account.paymentReminder

Description: The account.paymentReminder webhook is a provider-originated secured-credit event sent when the processor generates an upcoming-payment reminder for a secured-credit account. When the account belongs to a secured-credit group, data.securedCredit describes the relationship: role (collateral, primary_cardholder_credit, or authorized_user_credit), groupAnchorAccountId, collateralAccountId, and directParentAccountId (when applicable). The same shape applies to the other secured-credit events below.

Triggers:

  • Processor (e.g., Galileo) sends a payment_reminder_event

Example Payload:

{
  "uuid": "d3e4f5a6-b7c8-4d9e-0f1a-2b3c4d5e6f7a",
  "webhookType": "account.paymentReminder",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "accountNumber": "594100012345",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "securedCredit": {
      "role": "primary_cardholder_credit",
      "groupAnchorAccountId": "68950897f865c690e12e244a",
      "collateralAccountId": "689518b9m643l478n01n266j"
    },
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "3391",
      "timestamp": "2026-01-15 09:00:00 MST",
      "type": "payment_reminder_event",
      "balance_id": "5678",
      "eventType": "AccountEvent"
    }
  }
}

account.pastDuePaymentStatus

Description: The account.pastDuePaymentStatus webhook is a provider-originated secured-credit event sent when the processor reports a change in the past-due status of a secured-credit account's payment. When the account is a secured-credit account, data.securedCredit describes the linked secured-credit relationship.

Triggers:

  • Processor (e.g., Galileo) sends a past_due_payment_status_event

Example Payload:

{
  "uuid": "e4f5a6b7-c8d9-4e0f-1a2b-3c4d5e6f7a8b",
  "webhookType": "account.pastDuePaymentStatus",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "accountNumber": "594100012345",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "3391",
      "timestamp": "2026-01-15 09:00:00 MST",
      "type": "past_due_payment_status_event",
      "balance_id": "5678",
      "eventType": "AccountEvent"
    }
  }
}

account.autopayStatusChange

Description: The account.autopayStatusChange webhook is a provider-originated secured-credit event sent when the autopay configuration status changes on a secured-credit account (for example, autopay enabled or disabled). When the account is a secured-credit account, data.securedCredit describes the linked secured-credit relationship.

Triggers:

  • Processor (e.g., Galileo) sends an autopay_status_change_event

Example Payload:

{
  "uuid": "f5a6b7c8-d9e0-4f1a-2b3c-4d5e6f7a8b9c",
  "webhookType": "account.autopayStatusChange",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "accountNumber": "594100012345",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "3391",
      "timestamp": "2026-01-15 09:00:00 MST",
      "type": "autopay_status_change_event",
      "balance_id": "5678",
      "eventType": "AccountEvent"
    }
  }
}

account.autopaySuccess

Description: The account.autopaySuccess webhook is a provider-originated secured-credit event sent when an autopay payment succeeds on a secured-credit account. When the account is a secured-credit account, data.securedCredit describes the linked secured-credit relationship.

Triggers:

  • Processor (e.g., Galileo) sends an autopay_success_event

Example Payload:

{
  "uuid": "a6b7c8d9-e0f1-4a2b-3c4d-5e6f7a8b9c0d",
  "webhookType": "account.autopaySuccess",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "accountNumber": "594100012345",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "3391",
      "timestamp": "2026-01-15 09:00:00 MST",
      "type": "autopay_success_event",
      "balance_id": "5678",
      "eventType": "AccountEvent"
    }
  }
}

ACH Account Webhooks

achAccount.create

Description: The achAccount.create webhook is sent when a new ACH account is successfully linked to a user's account. It includes the ACH account ID and optional ZTM data.

Triggers:

  • Successful API call to the Create ACH Account endpoint (POST /v1/achaccount/create)

Example Payload:

{
  "uuid": "j9k0l1m2-n3o4-4p5q-6r7s-8t9u0v1w2x3y",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "m971no02o89n733679mn4l1l55m5392k",
  "responseBody": {
    "achAccountId": "689509a8g976d701f23f355b",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "achAccountId": "689509a8g976d701f23f355b",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "achAccount.create",
  "actionRequestor": {
    "source": "api"
  }
}

achAccount.remove

Description: The achAccount.remove webhook is sent when an ACH account is successfully removed (unlinked) from a user's account.

Triggers:

  • Successful API call to the Remove ACH Account endpoint (DELETE /v1/achaccount/{id})
  • ACH account removed via the appropriate SST role

Example Payload:

{
  "uuid": "k0l1m2n3-o4p5-4q6r-7s8t-9u0v1w2x3y4z",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "n082op13p90o844780no5m2m66n6403l",
  "responseBody": {
    "removed": true,
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "achAccountId": "689509a8g976d701f23f355b",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "achAccount.remove",
  "actionRequestor": {
    "source": "api"
  }
}

Card Webhooks

card.activate

Description: The card.activate webhook is sent when a card is successfully activated. It includes the card details and the change history showing the status change from inactive to active.

Triggers:

  • Successful API call to the Activate Card endpoint (POST /v1/card/{cardId}/activate)

Example Payload:

{
  "uuid": "l1m2n3o4-p5q6-4r7s-8t9u-0v1w2x3y4z5a",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "o193pq24q01p955891pq6n3n77p7514m",
  "responseBody": {
    "cardId": "68950ab9h087e812g34g466c",
    "status": "active",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.activate",
  "actionRequestor": {
    "source": "api"
  },
  "changes": [
    {
      "field": "status",
      "oldValue": "unactivated",
      "newValue": "active"
    }
  ]
}

card.frozen

Description: The card.frozen webhook is sent when a card is successfully frozen (temporarily disabled). The card can be unfrozen later.

Triggers:

  • Successful API call to the Update Card Status endpoint (PATCH /v1/card/{cardId}/modifyStatus) with freeze action
  • Card frozen via the appropriate SST role

Example Payload:

{
  "uuid": "m2n3o4p5-q6r7-4s8t-9u0v-1w2x3y4z5a6b",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "p204qr35r12q066902qr7o4o88q8625n",
  "responseBody": {
    "newStatus": "frozen",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.frozen",
  "actionRequestor": {
    "source": "api"
  }
}

card.unfrozen

Description: The card.unfrozen webhook is sent when a previously frozen card is successfully unfrozen (re-enabled).

Triggers:

  • Successful API call to the Update Card Status endpoint (PATCH /v1/card/{cardId}/modifyStatus) with unfreeze action
  • Card unfrozen via the appropriate SST role

Example Payload:

{
  "uuid": "n3o4p5q6-r7s8-4t9u-0v1w-2x3y4z5a6b7c",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "q315rs46s23r177013rs8p5p99r9736o",
  "responseBody": {
    "newStatus": "active",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.unfrozen",
  "actionRequestor": {
    "source": "api"
  }
}

card.replaced

Description: The card.replaced webhook is sent when a card is successfully replaced (e.g., due to loss or theft). A new card is issued and the old card is archived.

Triggers:

  • Successful API call to the Replace Card endpoint (POST /v1/card/{cardId}/replace)
  • Card replaced via the appropriate SST role

Example Payload:

{
  "uuid": "o4p5q6r7-s8t9-4u0v-1w2x-3y4z5a6b7c8d",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "r426st57t34s288124st9q6q00s0847p",
  "responseBody": {
    "card": {
      "cardId": "68950bcan198f923h45h577d",
      "cardNumber": "487093XXXXXX2308",
      "status": "unactivated"
    },
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.replaced",
  "actionRequestor": {
    "source": "api"
  },
  "changes": [
    {
      "field": "isArchived",
      "oldValue": false,
      "newValue": true
    },
    {
      "field": "status",
      "oldValue": "active",
      "newValue": "closed_lost_stolen"
    }
  ]
}

card.reissued

Description: The card.reissued webhook is sent when a card is successfully reissued (typically due to expiration). The existing card remains active until the new card is activated.

Triggers:

  • Successful API call to the Reissue Card endpoint (POST /v1/card/{cardId}/reissue)
  • Card reissued via the appropriate SST role

Example Payload:

{
  "uuid": "p5q6r7s8-t9u0-4v1w-2x3y-4z5a6b7c8d9e",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "s537tu68u45t399235tu0r7r11t1958q",
  "responseBody": {
    "cardNumber": "487093XXXXXX2307",
    "cardExpiryDate": "12/27",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.reissued",
  "actionRequestor": {
    "source": "api"
  }
}

card.resetPin

Description: The card.resetPin webhook is sent when a card's PIN fail count is successfully reset. This is typically done after multiple failed PIN attempts have locked the card.

Triggers:

  • Successful API call to the Reset Card PIN Fail Count endpoint (POST /v1/card/{cardId}/resetPinFailCount)
  • PIN fail count reset via the appropriate SST role

Example Payload:

{
  "uuid": "q6r7s8t9-u0v1-4w2x-3y4z-5a6b7c8d9e0f",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "t648uv79v56u400346uv1s8s22u2069r",
  "responseBody": {
    "cardId": "68950ab9h087e812g34g466c",
    "status": "active",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.resetPin",
  "actionRequestor": {
    "source": "sst",
    "sstRequestorUserId": "support456",
    "sstRequestorUserEmail": "[email protected]"
  }
}

card.mobileWalletProvision

Description: The card.mobileWalletProvision webhook is sent when a card is successfully provisioned to a mobile wallet (e.g., Apple Pay, Google Pay).

Triggers:

  • Successful API call to the Provision Mobile Wallet endpoint (POST /v1/card/{cardId}/mobileWalletProvision)

Example Payload:

{
  "uuid": "r7s8t9u0-v1w2-4x3y-4z5a-6b7c8d9e0f1g",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "u759vw80w67v511457vw2t9t33v3170s",
  "responseBody": {
    "encryptedCardData": "eyJhbGciOiJSU0EtT0FFUC0yNTYi...",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.mobileWalletProvision",
  "actionRequestor": {
    "source": "api"
  }
}

card.fetchImageUrl

Description: The card.fetchImageUrl webhook is sent when a card's display image URL is successfully retrieved. This is typically used to display a virtual card image to the user.

Triggers:

  • Successful API call to the Get Card Image URL endpoint (GET /v1/card/{cardId}/displayUrl)

Example Payload:

{
  "uuid": "s8t9u0v1-w2x3-4y4z-5a6b-7c8d9e0f1g2h",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "v860wx91x78w622568wx3u0u44w4281t",
  "responseBody": {
    "cardId": "68950ab9h087e812g34g466c",
    "url": "https://cardimages.example.com/display/abc123xyz",
    "expires": "2025-10-23T16:30:00.000Z",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.fetchImageUrl",
  "actionRequestor": {
    "source": "api"
  }
}

card.pinToken

Description: The card.pinToken webhook is sent when a PIN change token is successfully generated for a card. This token is used to securely change the card's PIN.

Triggers:

  • Successful API call to the Get PIN Change Token endpoint (GET /v1/card/{cardId}/pinChangeToken)

Example Payload:

{
  "uuid": "t9u0v1w2-x3y4-4z5a-6b7c-8d9e0f1g2h3i",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "w971xy02y89x733679xy4v1v55x5392u",
  "responseBody": {
    "cardId": "68950ab9h087e812g34g466c",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.pinToken",
  "actionRequestor": {
    "source": "api"
  }
}

card.pinChanged

Description: The card.pinChanged webhook is sent when a card's PIN is successfully changed. This confirms that the PIN change operation completed successfully.

Triggers:

  • Successful API call to the Change PIN endpoint (POST /v1/card/{cardId}/commitPinChange)

Example Payload:

{
  "uuid": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
  "accountId": "68950897f865c690e12e244a",
  "actionRequestor": {
    "source": "api"
  },
  "changes": [
    {
      "field": "lastUpdatedAt",
      "oldValue": "2025-10-23T17:10:00.000Z",
      "newValue": "2025-10-23T17:18:00.000Z"
    }
  ],
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "x082yz13z90y844780yz5w2w66y6403v",
  "responseBody": {
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.pinChanged"
}

card.statusUpdate

Description: The card.statusUpdate webhook is sent when a card's status is automatically updated due to an account status change (e.g., when an account is closed, all associated cards are also closed).

Triggers:

  • Automatic status update when the parent account's status is changed to closed

Example Payload:

{
  "uuid": "v1w2x3y4-z5a6-4b7c-8d9e-0f1g2h3i4j5k",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "y193za24a01z955891za6x3x77z7514w",
  "responseBody": {
    "newStatus": "closed",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.statusUpdate",
  "actionRequestor": {
    "source": "api"
  }
}

card.shipped

Description: The card.shipped webhook is sent when an emboss record has been created for a card. It includes shipping details such as the ship type, shipping address, and whether the card is an emboss reissue. The emboss record will be sent to the embosser in the next file delivery.

Triggers:

  • Provider (e.g., Galileo) generates an emboss record for a card.

Example Payload:

{
  "uuid": "w2x3y4z5-a6b7-4c8d-9e0f-1g2h3i4j5k6l",
  "webhookType": "card.shipped",
  "data": {
    "accountId": "69b44154054fb3d1cbc3439c",
    "productId": "68caf52136a4cd9dcfea7e18",
    "userId": "69b4414a054fb3d1cbc3438b",
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594101049718",
      "prod_id": "3391",
      "timestamp": "2026-03-13 10:23:33 MST",
      "type": "card_shipped",
      "addr1": "",
      "addr2": "",
      "balance_id": "4772",
      "cad": "4921",
      "city": "Woodbridge",
      "emboss_uuid": "",
      "is_emboss_reissue": "N",
      "msg_event_id": "66612",
      "open_to_buy": "0.00",
      "ship_type": "First Class Mail",
      "eventType": "AccountEvent"
    },
    "accountNumber": "594101049718",
    "address1": "123 Evergreen Ave",
    "address2": null,
    "balance": "0.00",
    "cardId": "69b44158054fb3d1cbc343aa",
    "city": "Woodbridge",
    "embossUUID": "",
    "isEmbossReissue": false,
    "shipType": "First Class Mail",
    "timestamp": "2026-03-13T17:23:33.000Z"
  }
}

Authorization Webhooks

auth.authApproved

Description: The auth.authApproved webhook is sent when a card authorization is approved. It includes detailed transaction data, provider information, merchant details, and optional ZTM (Zero Touch Monitoring) risk assessment data.

Triggers:

  • Card authorization approved by the payment processor

Example Payload:

{
  "uuid": "7f6c95d3-e169-40e7-8b27-4e713723295b",
  "webhookType": "auth.authApproved",
  "data": {
    "accountId": "69725ec0185ef9a6206c1a51",
    "productId": "6823a83e59a0f48f78787c28",
    "userId": "696951abcfca4cd4f1010f23",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "4179",
      "trans_code": "VIA",
      "calculated_balance": 900,
      "type": "A",
      "act_type": "VI",
      "auth_ts": "2026-01-22T19:21:59.000Z",
      "amt": -100,
      "settle_amt": 0,
      "settle_curr_code": "",
      "card_id": "3324",
      "auth_id": "4179",
      "formatted_merchant_desc": "test merchant",
      "merchant_id": "DBdWE8dnFQBYaqv",
      "mcc_code": "4480",
      "network_code": "V",
      "de022": "9000",
      "pmt_ref_no": "594101034322",
      "prog_id": "8594",
      "prod_id": "3391",
      "additionalFields": {
        "type": "auth",
        "balance_id": "3091",
        "card_not_present": "N",
        "currency": "840",
        "domestic": "Y",
        "merchant_location": "LT LAKE CITY, UTUS",
        "original_auth_id": "0",
        "response_code": "00",
        "response_reasons": "",
        "rules_results": "",
        "eventType": "Authorization",
        "provider": "galileo-webhook-transaction"
      }
    },
    "ztmData": {
      "riskLevel": "high",
      "providerSummary": {
        "riskConfigurationId": "cafUCmi4eLhMtLH6",
        "riskLevel": "high",
        "providerLevels": [
          {
            "provider": "hawk",
            "riskLevel": "high"
          }
        ]
      },
      "providerResponses": [
        {
          "provider": "hawk",
          "level": "high",
          "providerData": {
            "caseId": "02c76c7c-1849-40b0-a076-c92aa58a4fbd",
            "proceed": false,
            "tenantTransactionId": "eba61e556bac5bf1d98f8e44"
          }
        }
      ],
      "providerErrors": [],
      "isTrainingMode": true
    },
    "txnType": "purchase.authorization",
    "postedDate": null,
    "authDate": "2026-01-22T19:21:59.000Z",
    "amount": -100,
    "cardId": "69725ec2185ef9a6206c1a5a",
    "status": "pending",
    "txnRequestId": null,
    "mccCode": "4480",
    "balanceAfterTransaction": 900,
    "calculatedBalance": 900,
    "description": "test merchant",
    "txnKey": "gal_8594_vi_4179_v",
    "vendor": "galileo",
    "transactionId": "eba61e556bac5bf1d98f8e44"
  }
}

deniedAuth

Description: The deniedAuth webhook is sent when a card authorization is denied. It includes details about why the authorization was declined, including the response code and response reasons from the payment processor.

Please note that deniedAuth webhooks may map to one of the following subtypes:

  • deniedAuth.gas - Gas station partial-auth denial
  • deniedAuth.inactiveCard - Card not active
  • deniedAuth.invalidPin - Wrong PIN
  • deniedAuth.nsf - Insufficient funds

Triggers:

  • Card authorization denied by the payment processor

Example Payload:

{
  "uuid": "b10cc77d-7a78-4657-817a-547678fd25a3",
  "webhookType": "deniedAuth",
  "data": {
    "accountId": "69725ec0185ef9a6206c1a51",
    "productId": "6823a83e59a0f48f78787c28",
    "userId": "696951abcfca4cd4f1010f23",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "4178",
      "trans_code": "",
      "calculated_balance": 1000,
      "type": "",
      "act_type": "",
      "auth_ts": "2026-01-22T19:21:47.000Z",
      "amt": 100,
      "settle_amt": 0,
      "settle_curr_code": "",
      "card_id": "3324",
      "auth_id": "4178",
      "formatted_merchant_desc": "test merchant",
      "merchant_id": "gYck82zgjb8dlzU",
      "mcc_code": "4120",
      "network_code": "V",
      "de022": "9000",
      "pmt_ref_no": "594101034322",
      "prog_id": "8594",
      "prod_id": "3391",
      "additionalFields": {
        "type": "denied_auth",
        "balance_id": "3091",
        "currency": "840",
        "domestic": "Y",
        "merchant_location": "LT LAKE CITY, UTUS",
        "response_code": "5C",
        "response_reasons": "Token not present when required for Card Present transactions",
        "rules_results": "",
        "eventType": "Authorization",
        "provider": "galileo-webhook-transaction"
      }
    },
    "txnType": "other.denied_auth",
    "postedDate": null,
    "authDate": "2026-01-22T19:21:47.000Z",
    "amount": 100,
    "cardId": "69725ec2185ef9a6206c1a5a",
    "status": "settled",
    "txnRequestId": null,
    "mccCode": "4120",
    "balanceAfterTransaction": 1000,
    "calculatedBalance": 1000,
    "description": "test merchant",
    "txnKey": "gal_8594_da_4178_v",
    "vendor": "galileo",
    "transactionId": "85edd5a0113a084619769937"
  }
}

auth.expiration

Description: The auth.expiration webhook is sent when a card authorization hold expires without being settled. This typically occurs when a merchant authorizes a transaction but never submits it for settlement within the network's time window. When the authorization is strictly matched in Spidr, data.transactionId, data.txnKey, and data.originalTransactionId identify that existing authorization. These fields are omitted when no persisted transaction is matched.

Triggers:

  • Processor (e.g., Galileo) sends an auth_exp event when an authorization hold expires

Example Payload:

{
  "uuid": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
  "webhookType": "auth.expiration",
  "data": {
    "accountId": "69ab2c20baeae551080cd4c2",
    "productId": "6823a83e59a0f48f78787c29",
    "userId": "69ab2c1ebaeae551080cd4b2",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "7910",
      "trans_code": "VXA",
      "calculated_balance": 4950,
      "type": "A",
      "act_type": "VX",
      "auth_ts": "2026-03-06T19:39:30.000Z",
      "amt": -25,
      "card_id": "4867",
      "auth_id": "7910",
      "formatted_merchant_desc": "TEST MERCHANT",
      "merchant_id": "v2Me7RjU5UNQdZB",
      "mcc_code": "5411",
      "network_code": "V",
      "pmt_ref_no": "594101049171",
      "prog_id": "8594",
      "prod_id": "3391",
      "additionalFields": {
        "type": "auth_exp",
        "balance_id": "4714",
        "merchant_location": "LT LAKE CITY, UTUS",
        "eventType": "Authorization",
        "provider": "galileo-webhook-transaction"
      }
    },
    "txnType": "purchase.expiration",
    "postedDate": null,
    "authDate": "2026-03-06T19:39:30.000Z",
    "amount": -25,
    "cardId": "69ab2c25baeae551080cd4ce",
    "status": "expired",
    "txnRequestId": null,
    "mccCode": "5411",
    "balanceAfterTransaction": 4950,
    "calculatedBalance": 4950,
    "description": "TEST MERCHANT",
    "txnKey": "gal_8594_vi_7910_v",
    "vendor": "galileo",
    "transactionId": "64f8f0c2b1a2d3e4f5a60718",
    "originalTransactionId": "64f8f0c2b1a2d3e4f5a60718"
  }
}

auth.expirationReversal

Description: The auth.expirationReversal webhook is sent when a previously expired authorization is reversed. This uses the same payload shape as auth.expiration. When reconciliation succeeds, data.transactionId and data.txnKey identify the existing reversal row updated by the event. When its original authorization is also matched, data.originalTransactionId identifies that authorization. Transaction identity is omitted when the reversal is not strictly matched, and data.originalTransactionId is omitted when its parent is not matched.

Triggers:

  • Processor (e.g., Galileo) sends an auth_exp_reversal event when an expired authorization is reversed

Example Payload:

{
  "uuid": "d4e5f6g7-b8c9-4d0e-1f2g-3h4i5j6k7l8m",
  "webhookType": "auth.expirationReversal",
  "data": {
    "accountId": "69ab2c20baeae551080cd4c2",
    "productId": "6823a83e59a0f48f78787c29",
    "userId": "69ab2c1ebaeae551080cd4b2",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "7911",
      "trans_code": "VXR",
      "calculated_balance": 4975,
      "type": "A",
      "act_type": "VX",
      "auth_ts": "2026-03-06T19:40:00.000Z",
      "amt": 25,
      "card_id": "4867",
      "auth_id": "7911",
      "formatted_merchant_desc": "TEST MERCHANT",
      "merchant_id": "v2Me7RjU5UNQdZB",
      "mcc_code": "5411",
      "network_code": "V",
      "pmt_ref_no": "594101049171",
      "prog_id": "8594",
      "prod_id": "3391",
      "additionalFields": {
        "type": "auth_exp_reversal",
        "balance_id": "4714",
        "merchant_location": "LT LAKE CITY, UTUS",
        "eventType": "Authorization",
        "provider": "galileo-webhook-transaction"
      }
    },
    "txnType": "purchase.expirationReversal",
    "postedDate": null,
    "authDate": "2026-03-06T19:40:00.000Z",
    "amount": 25,
    "cardId": "69ab2c25baeae551080cd4ce",
    "status": "expired",
    "txnRequestId": null,
    "mccCode": "5411",
    "balanceAfterTransaction": 4975,
    "calculatedBalance": 4975,
    "description": "TEST MERCHANT",
    "txnKey": "gal_8594_vr_7911_v",
    "vendor": "galileo",
    "transactionId": "267c8g929b304b4517c3df9b",
    "originalTransactionId": "64f8f0c2b1a2d3e4f5a60718"
  }
}

auth.authPayment

Description: The auth.authPayment webhook is sent when an incoming Original Credit Transaction (OCT) is authorized — i.e., a card load from an external source such as Visa, Maestro, or an Allpoint ATM. The auth.authPayment acts as the authorization hold; the subsequent transaction.payment event is the actual credit posting.

Triggers:

  • Processor (e.g., Galileo) sends an auth_payment event when an incoming OCT authorization is received

Example Payload:

{
  "uuid": "e5f6g7h8-c9d0-4e1f-2g3h-4i5j6k7l8m9n",
  "webhookType": "auth.authPayment",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "8100",
      "trans_code": "MCA",
      "calculated_balance": 1100,
      "type": "A",
      "act_type": "MC",
      "auth_ts": "2026-01-15T14:00:00.000Z",
      "amt": 100,
      "settle_amt": 0,
      "settle_curr_code": "",
      "card_id": "3035",
      "auth_id": "8100",
      "formatted_merchant_desc": "CARD LOAD",
      "merchant_id": "oCTLoadMerchant1",
      "mcc_code": "6012",
      "network_code": "M",
      "pmt_ref_no": "594100012345",
      "prog_id": "8594",
      "prod_id": "3391",
      "additionalFields": {
        "type": "auth_payment",
        "balance_id": "5678",
        "eventType": "Authorization",
        "provider": "galileo-webhook-transaction"
      }
    },
    "txnType": "purchase.authorization",
    "postedDate": null,
    "authDate": "2026-01-15T14:00:00.000Z",
    "amount": 100,
    "cardId": "68950ab9h087e812g34g466c",
    "status": "pending",
    "txnRequestId": null,
    "mccCode": "6012",
    "balanceAfterTransaction": 1100,
    "calculatedBalance": 1100,
    "description": "CARD LOAD",
    "txnKey": "gal_8594_mc_8100_m",
    "vendor": "galileo",
    "transactionId": "a1b2c3d4e5f6g7h8i9j0k1l2"
  }
}

Transaction Webhooks

transaction.createAch

Description: The transaction.createAch webhook is sent when an ACH transaction (credit or debit) is successfully initiated. It includes the transaction details such as amount, direction (debit/credit), and description.

Triggers:

  • Successful API call to the Create ACH Transfer endpoint (POST /v1/transaction/createAchTransfer)

Example Payload:

{
  "uuid": "w2x3y4z5-a6b7-4c8d-9e0f-1g2h3i4j5k6l",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "ACH_TRANSFER_z204ab35b12a066902ab7y4y88a8625x",
  "responseBody": {
    "achRequestId": "ACH_TRANSFER_z204ab35b12a066902ab7y4y88a8625x",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "achAccountId": "689509a8g976d701f23f355b",
  "amount": 250.0,
  "debitCreditIndicator": "debit",
  "description": "Rent payment",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "transaction.createAch",
  "actionRequestor": {
    "source": "api"
  }
}

transaction.createFee

Description: The transaction.createFee webhook is sent when a fee is successfully applied to an account. It includes the fee type, amount, and resulting account balances.

Triggers:

  • Successful API call to the Create Fee endpoint (POST /v1/transaction/createFee)
  • Fee applied via the appropriate SST role

Example Payload:

{
  "uuid": "x3y4z5a6-b7c8-4d9e-0f1g-2h3i4j5k6l7m",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "FEE_a315bc46c23b177013bc8z5z99b9736y",
  "responseBody": {
    "status": "success",
    "oldBalance": 1000.0,
    "newBalance": 990.0,
    "feeTransactionId": "FEE_a315bc46c23b177013bc8z5z99b9736y",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "transaction.createFee",
  "feeType": "monthly_maintenance",
  "amount": 10.0,
  "actionRequestor": {
    "source": "api"
  }
}

transaction.reverseFee

Description: The transaction.reverseFee webhook is sent when a previously applied fee is successfully reversed (refunded). It includes the original fee transaction ID and the reversal details.

Triggers:

  • Successful API call to the Reverse Fee endpoint (POST /v1/transaction/reverseFee)
  • Fee reversed via the appropriate SST role

Example Payload:

{
  "uuid": "y4z5a6b7-c8d9-4e0f-1g2h-3i4j5k6l7m8n",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "FEE_b426cd57d34c288124cd9a6a00c0847z",
  "responseBody": {
    "status": "success",
    "oldBalance": 990.0,
    "newBalance": 1000.0,
    "reversalTransactionId": "FEE_b426cd57d34c288124cd9a6a00c0847z",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "transaction.reverseFee",
  "originalFeeTransactionId": "FEE_a315bc46c23b177013bc8z5z99b9736y",
  "actionRequestor": {
    "source": "sst",
    "sstRequestorUserId": "support789",
    "sstRequestorUserEmail": "[email protected]"
  }
}

transaction.adjustment

Description: The transaction.adjustment webhook is sent when an adjustment transaction (credit or debit) is successfully applied to an account. Adjustments are typically used for corrections, manual balance modifications, adjustment-path card load reversals, or incoming ACH adjustments from external sources. For incoming ACH adjustments, the webhook includes originator details (sender's bank information). For adjustment-path card load reversals, the webhook includes data.relatedTransactionId when the original load transaction is already matched in Spidr.

Triggers:

  • Successful API call to the Create Adjustment endpoint (POST /v1/transaction/createAdjustment)
  • Adjustment created via the appropriate SST role
  • Incoming ACH adjustment received from an external source (provider-originated)
  • Provider-originated adjustment-path card load reversal

Example Payload (Incoming ACH Adjustment):

{
  "uuid": "z5a6b7c8-d9e0-4f1g-2h3i-4j5k6l7m8n9o",
  "webhookType": "transaction.adjustment",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "2350",
      "trans_code": "ADJC",
      "calculated_balance": 1050.0,
      "type": "CR",
      "act_type": "AD",
      "auth_ts": "2026-01-06T14:30:00.000Z",
      "amt": 50.0,
      "card_id": "3035",
      "ach_trans_id": "5045983826",
      "orig_name": "ABC Bank",
      "orig_acct_number": "265493042",
      "odfi_routing_number": "325491456",
      "details": "ACH Credit Adjustment",
      "prog_id": "8594",
      "prod_id": "3391"
    },
    "txnType": "other.custom",
    "txnSubType": "CR",
    "postedDate": "2026-01-06T14:30:00.000Z",
    "authDate": "2026-01-06T14:30:00.000Z",
    "amount": 50.0,
    "cardId": "68950ab9h087e812g34g466c",
    "status": "settled",
    "balanceAfterTransaction": 1050.0,
    "calculatedBalance": 1050.0,
    "description": "ACH Credit Adjustment",
    "txnKey": "gal_8594_ad_2350",
    "vendor": "galileo",
    "transactionId": "f186e89d958925c8g1e4fd9f"
  }
}

ACH Originator Fields (in providerDetails):

FieldTypeDescription
orig_namestringOriginator name - the name of the sending institution or entity
orig_acct_numberstringOriginator account number - the source account for the incoming ACH
odfi_routing_numberstringODFI routing number - Originating Depository Financial Institution routing number

transaction.reverseAdjustment

Description: The transaction.reverseAdjustment webhook is sent when a previously applied adjustment is successfully reversed. It includes the original adjustment transaction ID and the reversal details.

Triggers:

  • Successful API call to the Reverse Adjustment endpoint (POST /v1/transaction/reverseAdjustment)
  • Adjustment reversed via the appropriate SST role

Example Payload:

{
  "uuid": "d8e9f0a1-b2c3-4d4e-5f6g-7h8i9j0k1l2m",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "ADJ_c537de68e45d399235de0b7b11d1958a",
  "responseBody": {
    "status": "success",
    "oldBalance": 950.0,
    "newBalance": 1000.0,
    "adjustmentTransactionId": "ADJ_b426cd57d34c288124cd9a6a00c0847z",
    "reversalAdjustmentTransactionId": "ADJ_c537de68e45d399235de0b7b11d1958a",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "transaction.reverseAdjustment",
  "originalAdjustmentTransactionId": "ADJ_b426cd57d34c288124cd9a6a00c0847z",
  "reversalTransactionId": "68f1b2c3d4e5f6a7b8c9d0e1",
  "actionRequestor": {
    "source": "api"
  }
}

transaction.payment

Description: The transaction.payment webhook is sent when a payment transaction is successfully processed. This includes both API-initiated payments and incoming ACH payments from external sources. For incoming ACH payments, the webhook includes originator details (sender's bank information).

Triggers:

  • Successful API call to the Create Payment endpoint (POST /v1/transaction/createPayment)
  • Payment created via the appropriate SST role
  • Incoming ACH payment received from an external source (provider-originated)

Example Payload (Incoming ACH Payment):

{
  "uuid": "6abf3b44-efb9-4315-b6a3-8b6b74eb864a",
  "webhookType": "transaction.payment",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "1450",
      "trans_code": "PMDD",
      "calculated_balance": 1892.34,
      "type": "DD",
      "act_type": "PM",
      "auth_ts": "2026-01-06T22:17:24.000Z",
      "amt": 12.34,
      "card_id": "3035",
      "pmt_ref_no": "594101032359",
      "ach_trans_id": "5045983825",
      "orig_name": "ABC Bank",
      "orig_acct_number": "265493042",
      "odfi_routing_number": "031101169",
      "details": "ABC Company, Subscribe, #789654",
      "prog_id": "8594",
      "prod_id": "3391"
    },
    "txnType": "other.custom",
    "txnSubType": "DD",
    "postedDate": "2026-01-06T22:17:24.000Z",
    "authDate": "2026-01-06T22:17:24.000Z",
    "amount": 12.34,
    "cardId": "68950ab9h087e812g34g466c",
    "status": "settled",
    "balanceAfterTransaction": 1892.34,
    "calculatedBalance": 1892.34,
    "description": "ABC Company, Subscribe, #789654",
    "txnKey": "gal_8594_pm_1450",
    "vendor": "galileo",
    "transactionId": "e075d78c847814b7f0d3ec8e"
  }
}

ACH Originator Fields (in providerDetails):

FieldTypeDescription
orig_namestringOriginator name - the name of the sending institution or entity
orig_acct_numberstringOriginator account number - the source account for the incoming ACH
odfi_routing_numberstringODFI routing number - Originating Depository Financial Institution routing number

transaction.a2a

Description: The transaction.a2a webhook is sent when an account-to-account (A2A) transfer is successfully initiated between two accounts within the same system.

Triggers:

  • Successful API call to the Create A2A Transfer endpoint (POST /v1/transaction/createA2ATransfer)

Example Payload:

{
  "uuid": "b7c8d9e0-f1g2-4h3i-4j5k-6l7m8n9o0p1q",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "ACCOUNT_TO_ACCOUNT_e759fg80g67f511457fg2d9d33f3170c",
  "responseBody": {
    "oldBalance": 1000.0,
    "newBalance": 900.0,
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "transaction.a2a",
  "transferToAccountId": "68950bc0i209g034j56j688e",
  "amount": 100.0,
  "message": "Payment for dinner",
  "senderMessage": "Payment for dinner",
  "actionRequestor": {
    "source": "api"
  }
}

transaction.cancelAch

Description: The transaction.cancelAch webhook is sent when a pending ACH transaction is successfully canceled. Only ACH transactions in certain statuses can be canceled.

Triggers:

  • Successful API call to the Cancel ACH Transfer endpoint (POST /v1/transaction/cancelAchTransfer)
  • ACH transaction canceled via the appropriate SST role

Example Payload:

{
  "uuid": "c8d9e0f1-g2h3-4i4j-5k6l-7m8n9o0p1q2r",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "ACH_TRANSFER_f860gh91h78g622568gh3e0e44g4281d",
  "responseBody": {
    "status": "canceled",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "achRequestId": "ACH_TRANSFER_z204ab35b12a066902ab7y4y88a8625x",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "transaction.cancelAch",
  "actionRequestor": {
    "source": "api"
  }
}

transaction.settle

Description: The transaction.settle webhook is sent when a card transaction is settled. Settlement occurs when a previously authorized transaction is finalized and the funds are actually transferred. It includes detailed transaction and merchant information from the payment processor. When the parent authorization or completion is already matched in Spidr, data.relatedTransactionId contains that Spidr transaction ID. Refunds and inbound card load reversals are excluded from this event; they are delivered as the dedicated transaction.refund and transaction.loadReversal events instead.

Triggers:

  • Card transaction settlement received from the payment processor

Example Payload:

{
  "uuid": "b7fd4a7c-8924-4eea-8118-e02d0072e08f",
  "webhookType": "transaction.settle",
  "data": {
    "accountId": "69725ec0185ef9a6206c1a51",
    "productId": "6823a83e59a0f48f78787c28",
    "userId": "696951abcfca4cd4f1010f23",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "4179",
      "trans_code": "VSA",
      "calculated_balance": 900,
      "type": "A",
      "act_type": "VS",
      "auth_ts": "2026-01-22T19:23:22.000Z",
      "amt": -100,
      "settle_amt": 0,
      "settle_curr_code": "",
      "card_id": "3324",
      "auth_id": "4179",
      "formatted_merchant_desc": "test merchant",
      "merchant_id": "DBdWE8dnFQBYaqv",
      "mcc_code": "4480",
      "network_code": "V",
      "pmt_ref_no": "594101034322",
      "prog_id": "8594",
      "prod_id": "3391",
      "additionalFields": {
        "type": "setl",
        "balance_id": "3091",
        "currency": "840",
        "expired_auth_id": "0",
        "merchant_location": "LT LAKE CITY, UTUS",
        "response_code": "",
        "settle_detail_id": "8210",
        "eventType": "Settlement",
        "provider": "galileo"
      }
    },
    "txnType": "purchase.settlement",
    "postedDate": "2026-01-22T19:23:23.424Z",
    "authDate": "",
    "amount": -100,
    "cardId": "69725ec2185ef9a6206c1a5a",
    "status": "settled",
    "txnRequestId": "4179",
    "balanceAfterTransaction": 900,
    "calculatedBalance": 900,
    "mccCode": "4480",
    "description": "No description available",
    "txnKey": "gal_8594_vs_4179",
    "parentAuthId": "4179",
    "vendor": "galileo",
    "transactionId": "e37cbe6298747cf35d48b1e8",
    "relatedTransactionId": "64f8f0c2b1a2d3e4f5a60719"
  }
}

transaction.loadReversal

Description: The transaction.loadReversal webhook is sent when a Galileo settlement event reverses a prior inbound card load. These events use data.txnType: "other.card_load_reversal". When the original card-load transaction is already matched in Spidr, data.relatedTransactionId contains that Spidr transaction ID.

Triggers:

  • Processor sends a Galileo settlement event with a load-reversal transaction type, such as U, V, K, q, y, yt, RW, vd, or ao

Example Payload:

{
  "uuid": "c24f8d2e-7b11-4d24-9dd9-3f8af35fb482",
  "webhookType": "transaction.loadReversal",
  "data": {
    "accountId": "69725ec0185ef9a6206c1a51",
    "productId": "6823a83e59a0f48f78787c28",
    "userId": "696951abcfca4cd4f1010f23",
    "txnType": "other.card_load_reversal",
    "amount": -50,
    "status": "settled",
    "transactionId": "e37cbe6298747cf35d48b1ea",
    "txnRequestId": "4179",
    "parentAuthId": "4179",
    "relatedTransactionId": "64f8f0c2b1a2d3e4f5a60721",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "type": "U",
      "act_type": "SE",
      "auth_id": "4179",
      "pmt_ref_no": "594101034322",
      "additionalFields": {
        "type": "setl",
        "settle_detail_id": "8210"
      }
    },
    "vendor": "galileo"
  }
}

transaction.refund

Description: The transaction.refund webhook is sent when a Galileo settlement refund or merchant credit returns funds after the original purchase. When the original purchase transaction is already matched in Spidr, data.relatedTransactionId contains that Spidr transaction ID.

Triggers:

  • Processor (e.g., Galileo) sends a settlement event that maps to a refund or merchant credit

Example Payload:

{
  "uuid": "a11f4d7c-8924-4eea-8118-e02d0072e08f",
  "webhookType": "transaction.refund",
  "data": {
    "accountId": "69725ec0185ef9a6206c1a51",
    "productId": "6823a83e59a0f48f78787c28",
    "userId": "696951abcfca4cd4f1010f23",
    "txnType": "purchase.refund",
    "amount": 25.33,
    "status": "settled",
    "transactionId": "e37cbe6298747cf35d48b1e9",
    "relatedTransactionId": "64f8f0c2b1a2d3e4f5a60720",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo"
    }
  }
}

transaction.paymentDelayed

Description: The transaction.paymentDelayed webhook is sent when a payment posting is delayed. This occurs when an incoming payment cannot be posted immediately and is queued for later processing.

Triggers:

  • Processor (e.g., Galileo) sends a pmt_delayed event when a payment is delayed

Example Payload:

{
  "uuid": "f6g7h8i9-d0e1-4f2g-3h4i-5j6k7l8m9n0o",
  "webhookType": "transaction.paymentDelayed",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "3200",
      "trans_code": "PMDD",
      "calculated_balance": 950,
      "type": "DD",
      "act_type": "PM",
      "auth_ts": "2026-01-20T10:00:00.000Z",
      "amt": 50,
      "card_id": "3035",
      "pmt_ref_no": "594100012345",
      "prog_id": "8594",
      "prod_id": "3391",
      "additionalFields": {
        "type": "pmt_delayed",
        "balance_id": "5678",
        "eventType": "Transaction",
        "provider": "galileo-webhook-transaction"
      }
    },
    "txnType": "other.custom",
    "postedDate": "2026-01-20T10:00:00.000Z",
    "authDate": "2026-01-20T10:00:00.000Z",
    "amount": 50,
    "cardId": "68950ab9h087e812g34g466c",
    "status": "settled",
    "txnRequestId": null,
    "balanceAfterTransaction": 950,
    "calculatedBalance": 950,
    "description": "Delayed Payment",
    "txnKey": "gal_8594_pm_3200",
    "vendor": "galileo",
    "transactionId": "b2c3d4e5f6g7h8i9j0k1l2m3",
    "achAccountId": "689509a8g976d701f23f355b"
  }
}

transaction.paymentSplit

Description: The transaction.paymentSplit webhook is sent when a payment is split into multiple postings. This can occur when a single payment is distributed across multiple accounts or posting periods.

Triggers:

  • Processor (e.g., Galileo) sends a pmt_split event when a payment is split

Example Payload:

{
  "uuid": "g7h8i9j0-e1f2-4g3h-4i5j-6k7l8m9n0o1p",
  "webhookType": "transaction.paymentSplit",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "3201",
      "trans_code": "PMSP",
      "calculated_balance": 975,
      "type": "SP",
      "act_type": "PM",
      "auth_ts": "2026-01-20T11:00:00.000Z",
      "amt": 25,
      "card_id": "3035",
      "pmt_ref_no": "594100012345",
      "prog_id": "8594",
      "prod_id": "3391",
      "additionalFields": {
        "type": "pmt_split",
        "balance_id": "5678",
        "eventType": "Transaction",
        "provider": "galileo-webhook-transaction"
      }
    },
    "txnType": "other.custom",
    "postedDate": "2026-01-20T11:00:00.000Z",
    "authDate": "2026-01-20T11:00:00.000Z",
    "amount": 25,
    "cardId": "68950ab9h087e812g34g466c",
    "status": "settled",
    "txnRequestId": null,
    "balanceAfterTransaction": 975,
    "calculatedBalance": 975,
    "description": "Split Payment",
    "txnKey": "gal_8594_pm_3201",
    "vendor": "galileo",
    "transactionId": "c3d4e5f6g7h8i9j0k1l2m3n4"
  }
}

transaction.incomingAchCreditFail

Description: The transaction.incomingAchCreditFail webhook is sent when an incoming ACH credit transaction fails. This can occur due to invalid account information, compliance holds, or processing errors.

Triggers:

  • Processor (e.g., Galileo) sends an ach_credit_fail event when an incoming ACH credit fails

Example Payload:

{
  "uuid": "h8i9j0k1-f2g3-4h4i-5j6k-7l8m9n0o1p2q",
  "webhookType": "transaction.incomingAchCreditFail",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "3300",
      "trans_code": "ACFR",
      "calculated_balance": 1000,
      "type": "CR",
      "act_type": "AC",
      "auth_ts": "2026-01-21T09:00:00.000Z",
      "amt": 200,
      "pmt_ref_no": "594100012345",
      "prog_id": "8594",
      "prod_id": "3391",
      "additionalFields": {
        "type": "ach_credit_fail",
        "balance_id": "5678",
        "eventType": "Transaction",
        "provider": "galileo-webhook-transaction"
      }
    },
    "txnType": "other.custom",
    "postedDate": "2026-01-21T09:00:00.000Z",
    "authDate": "2026-01-21T09:00:00.000Z",
    "amount": 200,
    "cardId": null,
    "status": "settled",
    "txnRequestId": null,
    "balanceAfterTransaction": 1000,
    "calculatedBalance": 1000,
    "description": "ACH Credit Failed",
    "txnKey": "gal_8594_ac_3300",
    "vendor": "galileo",
    "transactionId": "d4e5f6g7h8i9j0k1l2m3n4o5"
  }
}

transaction.incomingAchDebitFail

Description: The transaction.incomingAchDebitFail webhook is sent when an incoming ACH debit transaction fails. This can occur when the originating institution reverses or rejects the debit request.

Triggers:

  • Processor (e.g., Galileo) sends an ach_debit_fail event when an incoming ACH debit fails

Example Payload:

{
  "uuid": "i9j0k1l2-g3h4-4i5j-6k7l-8m9n0o1p2q3r",
  "webhookType": "transaction.incomingAchDebitFail",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "3301",
      "trans_code": "ADFR",
      "calculated_balance": 1000,
      "type": "DB",
      "act_type": "AD",
      "auth_ts": "2026-01-21T10:00:00.000Z",
      "amt": -150,
      "pmt_ref_no": "594100012345",
      "prog_id": "8594",
      "prod_id": "3391",
      "additionalFields": {
        "type": "ach_debit_fail",
        "balance_id": "5678",
        "eventType": "Transaction",
        "provider": "galileo-webhook-transaction"
      }
    },
    "txnType": "other.custom",
    "postedDate": "2026-01-21T10:00:00.000Z",
    "authDate": "2026-01-21T10:00:00.000Z",
    "amount": -150,
    "cardId": null,
    "status": "settled",
    "txnRequestId": null,
    "balanceAfterTransaction": 1000,
    "calculatedBalance": 1000,
    "description": "ACH Debit Failed",
    "txnKey": "gal_8594_ad_3301",
    "vendor": "galileo",
    "transactionId": "e5f6g7h8i9j0k1l2m3n4o5p6"
  }
}

transaction.achReturn

Description: The transaction.achReturn webhook is sent when an ACH return is received. ACH returns occur when a previously processed ACH transaction is returned by the receiving bank (e.g., insufficient funds, account closed, unauthorized transaction). The debCredInd field indicates the direction of the return — if the original transaction was a debit, the return is a credit, and vice versa.

Triggers:

  • Processor (e.g., Galileo) sends an ach_return event when an ACH return is received

Example Payload:

{
  "uuid": "j0k1l2m3-h4i5-4j6k-7l8m-9n0o1p2q3r4s",
  "webhookType": "transaction.achReturn",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo-webhook",
      "vendor": "galileo",
      "source_id": "3400",
      "trans_code": "ARDD",
      "calculated_balance": 750,
      "type": "DD",
      "act_type": "AR",
      "auth_ts": "2026-01-22T08:00:00.000Z",
      "amt": -250,
      "pmt_ref_no": "594100012345",
      "ach_acct_id": "12345",
      "deb_cred_ind": "D",
      "return_code": "R01",
      "prog_id": "8594",
      "prod_id": "3391",
      "additionalFields": {
        "type": "ach_return",
        "balance_id": "5678",
        "eventType": "Transaction",
        "provider": "galileo-webhook-transaction"
      }
    },
    "txnType": "other.custom",
    "postedDate": "2026-01-22T08:00:00.000Z",
    "authDate": "2026-01-22T08:00:00.000Z",
    "amount": -250,
    "cardId": null,
    "status": "settled",
    "txnRequestId": null,
    "balanceAfterTransaction": 750,
    "calculatedBalance": 750,
    "description": "ACH Return - R01",
    "txnKey": "gal_8594_ar_3400",
    "vendor": "galileo",
    "transactionId": "f6g7h8i9j0k1l2m3n4o5p6q7",
    "debCredInd": "C",
    "achAccountId": "689509a8g976d701f23f355b"
  }
}

ACH Return Fields:

FieldTypeDescription
debCredIndstringDirection of the return (C for credit return, D for debit return) — inverted from the original transaction
achAccountIdstringThe Spidr ACH account ID associated with the return, if available
providerDetails.return_codestringNACHA return reason code (e.g., R01 = Insufficient Funds, R02 = Account Closed, R03 = No Account)

Bill Pay Webhooks

Bill Pay webhooks cover biller management (adding and modifying billers) and the lifecycle of bill payments processed through the underlying processor. Biller-management events use the standard API/SST structure with actionRequestor and changes. Bill-payment transaction events are provider-originated and use the data wrapper with data.providerDetails.

biller.addElectronic

Description: The biller.addElectronic webhook is sent when an electronic biller is successfully added to an account for bill pay. The changes array reflects the fields set on the new biller.

Triggers:

  • Successful API call to add an electronic biller (Bill Pay)
  • Electronic biller added via the appropriate SST role

Example Payload:

{
  "uuid": "b7c8d9e0-f1a2-4b3c-4d5e-6f7a8b9c0d1e",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "64cad31f0ad07044e33c29600569b547",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "billerId": "689510a1f976e701g34g599c",
  "spidrActionId": "68950786e754b589d01d1339",
  "webhookType": "biller.addElectronic",
  "actionRequestor": {
    "source": "api"
  },
  "changes": [
    { "field": "accountNumber", "oldValue": null, "newValue": "12345678901" },
    { "field": "frequencyType", "oldValue": null, "newValue": "one_time" }
  ]
}

biller.addPaper

Description: The biller.addPaper webhook is sent when a paper (check) biller is successfully added to an account for bill pay. A paper biller is paid by a mailed check, so the biller record includes the payee's mailing details. The changes array reflects the fields set on the new biller.

Triggers:

  • Successful API call to add a paper biller (Bill Pay)
  • Paper biller added via the appropriate SST role

Example Payload:

{
  "uuid": "c8d9e0f1-a2b3-4c4d-5e6f-7a8b9c0d1e2f",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "75dbe42g1be18155f44d3a711680c658",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "billerId": "689510a1f976e701g34g599c",
  "spidrActionId": "68950786e754b589d01d1339",
  "webhookType": "biller.addPaper",
  "actionRequestor": {
    "source": "api"
  },
  "changes": [
    { "field": "name", "oldValue": null, "newValue": "Example Paper Biller" },
    { "field": "accountNumber", "oldValue": null, "newValue": "123456789" },
    { "field": "address1", "oldValue": null, "newValue": "123 Main St" },
    { "field": "city", "oldValue": null, "newValue": "Austin" },
    { "field": "state", "oldValue": null, "newValue": "TX" },
    { "field": "postalCode", "oldValue": null, "newValue": "78701" },
    { "field": "frequencyType", "oldValue": null, "newValue": "one_time" }
  ]
}

biller.modifyElectronic

Description: The biller.modifyElectronic webhook is sent when an existing electronic biller is successfully modified. The changes array lists the fields that changed with their old and new values.

Triggers:

  • Successful API call to modify an electronic biller (Bill Pay)
  • Electronic biller modified via the appropriate SST role

Example Payload:

{
  "uuid": "d9e0f1a2-b3c4-4d5e-6f7a-8b9c0d1e2f3a",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "f3345e4e814f1b2fa708004993ce7f07",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "billerId": "689510a1f976e701g34g599c",
  "spidrActionId": "68950786e754b589d01d1339",
  "webhookType": "biller.modifyElectronic",
  "actionRequestor": {
    "source": "api"
  },
  "changes": [
    { "field": "frequencyType", "oldValue": "one_time", "newValue": "monthly" },
    { "field": "nextDate", "oldValue": null, "newValue": "2026-02-15T00:00:00.000Z" },
    { "field": "endDate", "oldValue": null, "newValue": "2026-08-15T00:00:00.000Z" },
    { "field": "amount", "oldValue": null, "newValue": 100 }
  ]
}

biller.modifyPaper

Description: The biller.modifyPaper webhook is sent when an existing paper (check) biller is successfully modified. The changes array lists the fields that changed with their old and new values.

Triggers:

  • Successful API call to modify a paper biller (Bill Pay)
  • Paper biller modified via the appropriate SST role

Example Payload:

{
  "uuid": "e0f1a2b3-c4d5-4e6f-7a8b-9c0d1e2f3a4b",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "a4456f5f925g2c3gb819115aa4df8g18",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "billerId": "689510a1f976e701g34g599c",
  "spidrActionId": "68950786e754b589d01d1339",
  "webhookType": "biller.modifyPaper",
  "actionRequestor": {
    "source": "api"
  },
  "changes": [
    { "field": "frequencyType", "oldValue": "one_time", "newValue": "monthly" },
    { "field": "amount", "oldValue": 50, "newValue": 100 }
  ]
}

Bill Payment Transaction Events

Bill-payment transaction events are provider-originated and report the lifecycle of a bill payment at the processor. They share the provider data wrapper: data.providerDetails carries the raw processor event, and when the payment was initiated via the Unified API, data.responseBody, data.actionRequestor, and data.spidrActionId are also included.

webhookTypeGalileo typeDescription
transaction.billpaybillpayA bill payment debit has posted to the account
transaction.billpayRequestMadebillpay_request_madeA bill payment request was submitted to the processor
transaction.billpayCheckMailedbillpay_check_mailedA paper check for the bill payment was mailed
transaction.billpayCheckClearedbillpay_check_clearedA mailed paper check has cleared
transaction.billpayCancelledbillpay_cancelledA bill payment was cancelled
transaction.billpayExpiredbillpay_expiredA bill payment expired before completing
transaction.billpayRejectedbillpay_rejectedA bill payment was rejected
transaction.billpayLimitViolationbillpay_limit_violationA bill payment violated a configured limit
transaction.billpayRequestReturnedbillpay_request_returnedA submitted bill payment request was returned
transaction.billpayRetrybillpay_retryA bill payment is being retried
transaction.schedBillpayFailsched_billpay_failA scheduled bill payment failed

Example Payload (transaction.billpay):

{
  "uuid": "f1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",
  "webhookType": "transaction.billpay",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "3391",
      "prog_id": "8594",
      "timestamp": "2026-01-15 14:59:18 MST",
      "type": "billpay",
      "adj_id": "12912",
      "amount": "25.00",
      "balance_id": "5678",
      "billername": "Verizon Communications",
      "billpay_id": "18",
      "open_to_buy": "50.00",
      "eventType": "Transaction"
    },
    "responseBody": {
      "status": "processing",
      "oldBalance": 100,
      "newBalance": 75,
      "billPayRequestId": "BLP_fa41926563341061d14d1a4d7147635a",
      "spidrActionId": "68950786e754b589d01d1339"
    },
    "actionRequestor": {
      "source": "api"
    },
    "spidrActionId": "68950786e754b589d01d1339"
  }
}

Example Payload (transaction.billpayRequestMade):

{
  "uuid": "a2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d",
  "webhookType": "transaction.billpayRequestMade",
  "data": {
    "accountId": "68950897f865c690e12e244a",
    "productId": "67f2a93d743e864g1g80b8fd",
    "userId": "68950761e754b589d02d133c",
    "providerDetails": {
      "provider": "galileo",
      "pmt_ref_no": "594100012345",
      "prod_id": "3391",
      "prog_id": "8594",
      "timestamp": "2026-01-15 13:24:29 MST",
      "type": "billpay_request_made",
      "amount": "1.00",
      "balance_id": "6612",
      "billername": "Verizon Communications",
      "billpay_id": "106",
      "open_to_buy": "500.00",
      "eventType": "Transaction"
    },
    "responseBody": {
      "status": "pending",
      "oldBalance": 500,
      "newBalance": 499,
      "billPayRequestId": "BLP_6790113bdca89f1fc500a032e909f768",
      "spidrActionId": "68950786e754b589d01d1339"
    },
    "actionRequestor": {
      "source": "api"
    },
    "spidrActionId": "68950786e754b589d01d1339"
  }
}

Round-Up Webhooks

Round-Up webhooks report the lifecycle of a Round-Up enrollment and the status of each Round-Up sweep transfer. These are Spidr-generated events. The body carries a top-level envelope (companyId, userId, webhookType, requestorSource, requestorId, spidrActionId, requestId) and a nested payload object with the event-specific data.

roundup.created

Description: The roundup.created webhook is sent when a Round-Up enrollment is successfully created for a user. The payload contains the full enrollment configuration.

Triggers:

  • Successful API call to create a Round-Up enrollment

Example Payload:

{
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "roundup.created",
  "requestorSource": "api",
  "requestorId": "system",
  "spidrActionId": "68950786e754b589d01d1339",
  "requestId": "c6b9e3172957e86759dbe712284a162e",
  "payload": {
    "id": "689511b2g087f812h45h600d",
    "companyId": "6823a83c643d753f0f79a7ec",
    "userId": "68950761e754b589d02d133c",
    "status": "active",
    "calculationMode": "round_to_nearest_dollar",
    "currencyCode": "USD",
    "cadence": "weekly",
    "cadenceKey": 5,
    "cadenceMaxAmount": 50,
    "minimumSweepAmount": 1,
    "trackingAccounts": [
      { "type": "linked_institution_account", "trackingAccountId": "689512c3h198g923i56i711e" }
    ],
    "fundingAccounts": [
      { "type": "ach_account", "fundingAccountId": "689513d4i209h034j67j822f", "fundingPercentage": 100 }
    ],
    "receivingAccounts": [
      { "type": "spidr", "receivingAccountId": "689514e5j310i145k78k933g", "allocationPercentage": 100 }
    ],
    "createdAt": "2026-01-15T19:55:49.339Z",
    "updatedAt": "2026-01-15T19:55:49.339Z"
  }
}

roundup.updated

Description: The roundup.updated webhook is sent when a Round-Up enrollment's configuration is updated. The payload mirrors the enrollment object shown in roundup.created, reflecting the updated configuration.

Triggers:

  • Successful API call to update a Round-Up enrollment's configuration

roundup.paused

Description: The roundup.paused webhook is sent when a Round-Up enrollment is paused. While paused, no sweeps run for the enrollment. The payload contains the enrollment object with status set to paused, plus priorStatus (the status before the change) and pausedAt. Lifecycle events (paused, resumed, closed) all include priorStatus.

Triggers:

  • Round-Up enrollment status changed to paused (via API or SST)

roundup.resumed

Description: The roundup.resumed webhook is sent when a previously paused Round-Up enrollment is resumed. The payload contains the enrollment object with status set to active.

Triggers:

  • Round-Up enrollment status changed from paused back to active (via API or SST)

roundup.closed

Description: The roundup.closed webhook is sent when a Round-Up enrollment is closed. Once closed, the enrollment no longer runs sweeps. The payload contains the enrollment object with status set to closed.

Triggers:

  • Round-Up enrollment status changed to closed (via API or SST)

Round-Up Transfer Events

The roundup.transfer.* webhooks report the status of a Round-Up sweep transfer. Each sweep aggregates eligible round-ups over a period and transfers the total from the funding account(s) to the receiving account(s). The payload.calculation object shows how the sweep amount was derived, payload.includedRoundUps lists the contributing transactions, and payload.fundingAccountTransfers / payload.receivingAccountTransfers show the movement legs.

webhookTypepayload.statusMeaning
roundup.transfer.submittedfunding_submittedThe funding transfer has been submitted; receiving legs may still be pending
roundup.transfer.completesuccessThe sweep transfer completed successfully
roundup.transfer.failedfailedThe sweep transfer failed; see failureReason and the transfer legs
roundup.transfer.skippedskippedThe sweep was skipped; see skipReason (e.g. below_minimum_sweep_amount)

Example Payload (roundup.transfer.complete):

{
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "roundup.transfer.complete",
  "requestorSource": "api",
  "requestorId": "system",
  "spidrActionId": "68950786e754b589d01d1339",
  "requestId": "roundup-sweep:689511b2g087f812h45h600d:weekly:2026-01-12T00:00:00.000Z",
  "payload": {
    "roundUpSweepId": "689515f6k421j256l89l044h",
    "roundUpEnrollmentId": "689511b2g087f812h45h600d",
    "sweepKey": "roundup:6823a83c643d753f0f79a7ec:689511b2g087f812h45h600d:weekly:2026-01-12",
    "status": "success",
    "currencyCode": "USD",
    "period": {
      "cadence": "weekly",
      "startDate": "2026-01-12T00:00:00.000Z",
      "endDate": "2026-01-18T23:59:59.999Z"
    },
    "calculation": {
      "eligibleTransactionCount": 12,
      "eligibleTransactionAmount": 348.87,
      "calculatedRoundUpAmount": 5.13,
      "cadenceMaxAmount": 50,
      "finalAmount": 5.13,
      "calculationMode": "round_to_nearest_dollar"
    },
    "includedRoundUps": [
      { "transactionId": "689516a7l532k367m90m155i", "transactionCollection": "linked_institution_account_transaction", "roundUpAmount": 0.35 },
      { "transactionId": "689516a7l532k367m90m155j", "transactionCollection": "linked_institution_account_transaction", "roundUpAmount": 0.66 }
    ],
    "fundingAccountTransfers": [
      {
        "type": "spidr",
        "fundingAccountId": "689513d4i209h034j67j822f",
        "amount": 5.13,
        "fundingPercentage": 100,
        "status": "success",
        "transferId": "A2A_RUS_4d7f2a91c3b5e8d0a6f1b4c7e2d9a3f8b5c0e6d1",
        "a2aRequestId": "689517b8m643l478n01n266k",
        "submittedAt": "2026-01-19T06:00:09.557Z",
        "completedAt": "2026-01-19T06:00:09.855Z"
      }
    ],
    "receivingAccountTransfers": [
      {
        "type": "spidr",
        "receivingAccountId": "689514e5j310i145k78k933g",
        "amount": 5.13,
        "allocationPercentage": 100,
        "status": "success",
        "transferId": "A2A_RUS_4d7f2a91c3b5e8d0a6f1b4c7e2d9a3f8b5c0e6d1",
        "a2aRequestId": "689517b8m643l478n01n266k",
        "submittedAt": "2026-01-19T06:00:09.557Z",
        "completedAt": "2026-01-19T06:00:09.855Z"
      }
    ],
    "fundingCompletedAt": "2026-01-19T06:00:09.855Z",
    "receivingCompletedAt": "2026-01-19T06:00:09.855Z"
  }
}
📘

Each transfer leg carries a status (pending, submitted, success, or failed) plus a transferId and the underlying request ID (achRequestId for ACH-funded legs, a2aRequestId for internal transfers), with submittedAt / completedAt timestamps as the leg progresses. For roundup.transfer.failed, a top-level payload.failureReason is included and the affected legs carry status: "failed" with a per-leg failureReason. For roundup.transfer.skipped, payload.skipReason explains why the sweep did not run (for example, below_minimum_sweep_amount), and the transfer arrays are empty.

ZTM Webhooks

ZTM (Zero Touch Monitoring) webhooks are generated by the Spidr ZTM service to provide updates on linked institutions, identity verification sessions, watchlist screening statuses, business (KYB) verification sessions, and gated-action decisioning. These webhooks are delivered automatically when relevant state transitions occur in linked-institution, identity-verification, AML-screening, KYB, or manual-review decisioning workflows.

linkedInstitution.statusUpdate

Description: The linkedInstitution.statusUpdate webhook reports a Plaid linked institution that needs user action, is approaching a state that may need user action, or has been restored. These notifications describe the linked institution's Plaid Item state; they do not represent an exhaustive audit of every transaction-sync attempt.

Triggers:

Plaid conditionpayload.statepayload.statuspayload.actionRequired
ITEM_LOGIN_REQUIREDaction_requirederrorupdate_mode
ACCESS_NOT_GRANTEDaction_requirederrorupdate_mode
ITEM_NOT_FOUNDaction_requirederrornew_link
USER_PERMISSION_REVOKEDaction_requirederrornew_link
PENDING_DISCONNECTwarningsuccessupdate_mode
PENDING_EXPIRATIONwarningsuccessupdate_mode
Successful Item restorationrestoredsuccessnull

Remediation:

  • For ITEM_LOGIN_REQUIRED, launch update mode to repair authentication.
  • For ACCESS_NOT_GRANTED, launch update mode configured to request or restore the required Plaid product permission. An authentication-only update may not repair the missing permission.
  • For ITEM_NOT_FOUND or USER_PERMISSION_REVOKED, start a new-link flow.

ACCESS_NOT_GRANTED and warning states do not make the overall linked institution unusable. payload.status describes the reported Plaid Item transition and does not mirror the health of every service on the LinkedInstitution; use payload.state and payload.actionRequired to select remediation. A restored event is emitted after a previously action-required Item is repaired or a warning is cleared, either through Plaid's LOGIN_REPAIRED webhook or successful update mode completion.

Example Payload:

{
  "uuid": "3bc3c8a7-93a0-4f36-a0a1-06c7e10ab44e",
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "linkedInstitution.statusUpdate",
  "requestorSource": "api",
  "requestorId": "system",
  "spidrActionId": "68950786e754b589d01d1339",
  "requestId": "d082ef13f90e844780de5c2c66d6403b",
  "payload": {
    "linkedInstitutionId": "68fd8e78a3f4e73a4ad66b61",
    "userId": "68950761e754b589d02d133c",
    "provider": "plaid",
    "status": "error",
    "state": "action_required",
    "errorCode": "ITEM_LOGIN_REQUIRED",
    "actionRequired": "update_mode"
  }
}

Payload Fields:

FieldTypeDescription
linkedInstitutionIdstringThe linked institution whose Plaid Item state changed.
userIdstringThe user who owns the linked institution.
providerstringThe linked institution provider. This event currently uses plaid.
statussuccess | errorStatus of the reported Plaid Item transition; not a complete assessment of LinkedInstitution health.
statestringOne of action_required, warning, or restored.
errorCodestring (optional)The Plaid condition that caused an action-required or warning transition. Omitted for restored.
actionRequiredstring | nullupdate_mode, new_link, or null when the linked institution has been restored.
📘

ZTM submits this webhook once per observed state transition on a best-effort basis. Duplicate provider deliveries for the same active state are suppressed. Once accepted by the webhook service, normal webhook delivery retries apply; ZTM does not maintain a durable outbox for submission failures.

idvSession.manualReviewRequired

Description: The idvSession.manualReviewRequired webhook is sent when an identity verification session requires manual review by your compliance team. This typically occurs when automated verification cannot conclusively verify the user's identity.

Triggers:

  • Identity verification session flagged for manual review by the IDV provider (e.g., Plaid)

Example Payload:

{
  "uuid": "d8e9f0g1-h2i3-4j5k-6l7m-8n9o0p1q2r3s",
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "idvSession.manualReviewRequired",
  "idvSessionId": "689507c1f976e701g34g577e",
  "idvSessionStatus": "manual_review",
  "plaidIdvSessionId": "idv_session_abc123xyz",
  "requiresAction": "manual_review",
  "spidrActionId": "68950786e754b589d01d1339"
}

idvSession.needsDecision

Description: The idvSession.needsDecision webhook is sent when an identity verification session is awaiting a decision from your system after manual review.

Triggers:

  • Manual review completed and awaiting final decision

Example Payload:

{
  "uuid": "e9f0g1h2-i3j4-4k5l-6m7n-8o9p0q1r2s3t",
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "idvSession.needsDecision",
  "idvSessionId": "689507c1f976e701g34g577e",
  "idvSessionStatus": "needs_decision",
  "plaidIdvSessionId": "idv_session_def456uvw",
  "requiresAction": "decision",
  "spidrActionId": "68950786e754b589d01d1339"
}

idvSession.retry

Description: The idvSession.retry webhook is sent when a user needs to retry their identity verification session, typically due to incomplete or failed verification attempts.

Triggers:

  • User instructed to retry identity verification

Example Payload:

{
  "uuid": "f0g1h2i3-j4k5-4l6m-7n8o-9p0q1r2s3t4u",
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "idvSession.retry",
  "idvSessionId": "689507c1f976e701g34g577e",
  "idvSessionStatus": "retry",
  "plaidIdvSessionId": "idv_session_ghi789rst",
  "spidrActionId": "68950786e754b589d01d1339"
}

idvSession.rerun

Description: The idvSession.rerun webhook is sent when an identity verification session needs to be completely rerun with new parameters or criteria.

Triggers:

  • System or admin triggers rerun of identity verification

Example Payload:

{
  "uuid": "g1h2i3j4-k5l6-4m7n-8o9p-0q1r2s3t4u5v",
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "idvSession.rerun",
  "idvSessionId": "689507c1f976e701g34g577e",
  "idvSessionStatus": "rerun",
  "plaidIdvSessionId": "idv_session_jkl012mno",
  "spidrActionId": "68950786e754b589d01d1339"
}

idvSession.stale

Description: The idvSession.stale webhook is sent when an identity verification session has expired or become stale without completion.

Triggers:

  • Identity verification session exceeds time limit without completion

Example Payload:

{
  "uuid": "h2i3j4k5-l6m7-4n8o-9p0q-1r2s3t4u5v6w",
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "idvSession.stale",
  "idvSessionId": "689507c1f976e701g34g577e",
  "idvSessionStatus": "stale",
  "plaidIdvSessionId": "idv_session_pqr345stu",
  "spidrActionId": "68950786e754b589d01d1339"
}

watchlistScreening.statusUpdate

Description: The watchlistScreening.statusUpdate webhook is sent when a user's watchlist screening status changes (e.g., from pending to clear, or when a potential match is found).

Triggers:

  • Watchlist screening provider (e.g., Plaid) updates the screening status
  • Periodic re-screening detects status change

Example Payload:

{
  "uuid": "i3j4k5l6-m7n8-4o9p-0q1r-2s3t4u5v6w7x",
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "watchlistScreening.statusUpdate",
  "watchlistScreeningId": "689507d2g087f812h45h688f",
  "watchlistScreeningStatus": "clear",
  "spidrActionId": "68950786e754b589d01d1339"
}

watchlistScreening.hitUpdate

Description: The watchlistScreening.hitUpdate webhook is sent when there's an update to a watchlist hit (potential match) for a user, such as when additional information becomes available or the hit is reviewed.

Triggers:

  • New information available about a watchlist hit
  • Hit status changed (e.g., false positive confirmed)

Example Payload:

{
  "uuid": "j4k5l6m7-n8o9-4p0q-1r2s-3t4u5v6w7x8y",
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "watchlistScreening.hitUpdate",
  "watchlistScreeningId": "689507d2g087f812h45h688f",
  "watchlistHitId": "689507e3h198g923i56i799g",
  "watchlistScreeningStatus": "review",
  "spidrActionId": "68950786e754b589d01d1339"
}

user.cipStatusUpdate

Description: The user.cipStatusUpdate webhook is sent when a user's Customer Identification Program (CIP) status changes, indicating progression through the identity verification and compliance workflow.

Triggers:

  • User CIP status transitions (e.g., from pending to pass, pending to manual review, etc.)
  • Updates to CIP-related data

Example Payload:

{
  "uuid": "k5l6m7n8-o9p0-4q1r-2s3t-4u5v6w7x8y9z",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "68950786e754b589d01d1338",
  "responseBody": {
    "cipStatus": "pass",
    "updated": true,
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "user.cipStatusUpdate",
  "actionRequestor": {
    "source": "user",
    "userId": "68950761e754b589d02d133d",
    "userEmail": "[email protected]",
    "userIdSource": "internal"
  },
  "changes": [
    {
      "field": "cip.status",
      "oldValue": "pending",
      "newValue": "pass"
    }
  ]
}

Note: Automatic and manual CIP status decisions use this same delivered payload structure. The webhook processor adds the uuid to the emitted event.

spidrAction.needsDecision

Description: The spidrAction.needsDecision webhook is sent when a gated action requires a manual decision from your system (approve or decline) before it can proceed. This is the mechanism behind ZTM manual review: when an action such as user creation or card activation is held for review, this webhook notifies you that a decision is needed. payload.actionType identifies the held action. When the action relates to an account or card, top-level accountId and cardId fields are also included in the envelope (this applies to all spidrAction.* events).

Triggers:

  • A gated action enters the awaiting-decision state (for example, ZTM flags it for manual review)

Example Payload:

{
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "spidrAction.needsDecision",
  "requestorSource": "api",
  "requestorId": "system",
  "spidrActionId": "68950786e754b589d01d1339",
  "requestId": "638a6c1df629d620c9a8f23192f29a19",
  "payload": {
    "actionType": "user_create",
    "status": "awaiting_decision",
    "changes": { "field": "status", "oldValue": "pending", "newValue": "awaiting_decision" }
  }
}

spidrAction.approved

Description: The spidrAction.approved webhook is sent when a gated action is approved (automatically or via a manual decision) and is allowed to proceed. payload.decision and payload.decisionDetails describe who made the decision and how.

Triggers:

  • A gated action is approved (auto-decisioned or manually approved)

Example Payload:

{
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "spidrAction.approved",
  "requestorSource": "user",
  "requestorId": "68950fa1b2c3d4e5f6a7b8c9",
  "spidrActionId": "68950786e754b589d01d1339",
  "requestId": "638a6c1df629d620c9a8f23192f29a19",
  "payload": {
    "actionType": "user_create",
    "status": "success",
    "changes": { "field": "status", "oldValue": "awaiting_decision", "newValue": "success" },
    "decision": "approved",
    "decisionDetails": {
      "source": "user",
      "autoDecisioned": false,
      "userId": "68950fa1b2c3d4e5f6a7b8c9",
      "userIdSource": "internal",
      "reason": "Approved after manual review",
      "decisionDate": "2026-01-15T20:19:22.657Z"
    }
  }
}

spidrAction.declined

Description: The spidrAction.declined webhook is sent when a gated action is declined (manually or automatically). The action does not proceed. It shares the envelope shown above; payload.status is blocked, payload.decision is declined, and payload.decisionDetails describes the decision. For automatic expiry declines, decisionDetails.source is system with autoDecisioned: true, and payload.expiresAt carries the expiry deadline that passed.

Triggers:

  • A gated action is declined (auto-declined or manually declined), including automatic expiry of an action left undecided past its window

Example Payload:

{
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "spidrAction.declined",
  "requestorSource": "user",
  "requestorId": "68950fa1b2c3d4e5f6a7b8c9",
  "spidrActionId": "68950786e754b589d01d1339",
  "requestId": "638a6c1df629d620c9a8f23192f29a19",
  "payload": {
    "actionType": "user_create",
    "status": "blocked",
    "changes": { "field": "status", "oldValue": "awaiting_decision", "newValue": "blocked" },
    "decision": "declined",
    "decisionDetails": {
      "source": "user",
      "autoDecisioned": false,
      "userId": "68950fa1b2c3d4e5f6a7b8c9",
      "userIdSource": "internal",
      "reason": "Declined after manual review",
      "decisionDate": "2026-01-15T20:19:22.657Z"
    }
  }
}

spidrAction.failed

Description: The spidrAction.failed webhook is sent when a gated action fails during processing and cannot complete. This includes the case where the action was approved but the downstream execution then failed; in that case payload.decision and payload.decisionDetails reflect the approval that preceded the failure. payload.error contains a message and, when available, a code describing the failure.

Triggers:

  • A gated action fails while being processed (for example, a downstream provider error during execution after approval)

Example Payload:

{
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "spidrAction.failed",
  "requestorSource": "user",
  "requestorId": "68950fa1b2c3d4e5f6a7b8c9",
  "spidrActionId": "68950786e754b589d01d1339",
  "requestId": "638a6c1df629d620c9a8f23192f29a19",
  "accountId": "68950897f865c690e12e244a",
  "cardId": "68950ab9h087e812g34g466c",
  "payload": {
    "actionType": "card_update.reissue",
    "status": "failed",
    "changes": { "field": "status", "oldValue": "awaiting_decision", "newValue": "failed" },
    "decision": "approved",
    "decisionDetails": {
      "source": "user",
      "autoDecisioned": false,
      "userId": "68950fa1b2c3d4e5f6a7b8c9",
      "userIdSource": "internal",
      "reason": "Approved after manual review",
      "decisionDate": "2026-01-15T17:40:29.316Z"
    },
    "error": {
      "message": "Active card not found."
    }
  }
}

kybSession.manualReviewRequired

Description: The kybSession.manualReviewRequired webhook is sent when a business (KYB) verification session is flagged for manual review by the KYB provider. It includes the kybSessionId and passes the full provider KYB result through data.providerDetails. The changes object reflects the transition into manual review.

Triggers:

  • The KYB provider (e.g., Sardine) returns an in-review / manual-review result for a business verification

Example Payload:

{
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "kybSession.manualReviewRequired",
  "requestorSource": "api",
  "requestorId": "system",
  "spidrActionId": "68950786e754b589d01d1339",
  "requestId": "cdbc5f737c95844c49c18726823dd224",
  "kybSessionId": "689513d4i209h034j67j822f",
  "providerDetails": {
    "id": "87b6c1fe-2774-4e23-88e9-e04b330f6696",
    "type": "business_update.kyb",
    "provider": "sardine",
    "webhook_data": {
      "id": 750172,
      "trackingId": "68950761e754b589d02d133c",
      "status": "in_review",
      "name": "Example Business LLC",
      "kyb": { "status": "success" }
    }
  },
  "changes": { "field": "requiresManualReview", "oldValue": false, "newValue": true }
}
📘

providerDetails passes through the full provider KYB result (business details, verification tasks, watchlist screening, SOS registrations, and industry classification). It is trimmed above for brevity.

kybSession.needsDecision

Description: The kybSession.needsDecision webhook is sent when a KYB session is awaiting a decision from your system after manual review. It is the business (KYB) counterpart to idvSession.needsDecision. The kybSessionId identifies the session awaiting the decision.

Triggers:

  • KYB manual review completed and awaiting a final decision

Example Payload:

{
  "companyId": "6823a83c643d753f0f79a7ec",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "kybSession.needsDecision",
  "requestorSource": "user",
  "requestorId": "68950fa1b2c3d4e5f6a7b8c9",
  "spidrActionId": "68950786e754b589d01d1339",
  "requestId": "df46g848g06955d5ad29837934ee335",
  "kybSessionId": "689513d4i209h034j67j822f"
}

Note: These ZTM webhooks may have different payload structures than standard Unified API webhooks, as they originate from the ZTM service. Refer to the ZTM service documentation for detailed payload specifications.

Common Webhook Fields

📘

Please note that provider-originated webhooks wrap their payload in a data object and include providerDetails while API/SST initiated webhooks use a flat structure with responseBody, actionRequestor, and changes.

All webhooks share the following common fields:

FieldTypeDescription
uuidstringUnique identifier for the webhook event
companyIdstringThe company ID associated with the action
requestIdstringThe request ID that triggered this webhook
responseBodyobjectThe response body from the original API call
spidrActionIdstringThe ID of the SpidrAction that triggered this webhook
userIdstringThe ID of the user associated with the action
webhookTypestringThe type of webhook (e.g., "user.edit", "account.create")
actionRequestorobjectInformation about who/what initiated the action

ActionRequestor Object

The actionRequestor object contains information about the source of the action:

FieldTypeDescription
sourcestringEither "api" or "sst" indicating the source of the request
sstRequestorUserIdstring (optional)If source is "sst", the user ID of the SST user who made the request
sstRequestorUserEmailstring (optional)If source is "sst", the email of the SST user who made the request

Webhook Delivery

Webhooks are delivered via HTTP POST requests to the configured webhook URL for your company. The webhook service will:

  1. Send the webhook payload as JSON in the request body
  2. Include a Content-Type: application/json header
  3. Retry failed deliveries with exponential backoff
  4. Sign the request for verification

Best Practices

  1. Idempotency: Always check the uuid field to ensure you don't process the same webhook twice
  2. Validation: Verify the webhook signature to ensure it came from Spidr
  3. Async Processing: Return a 200 OK response quickly and process the webhook asynchronously
  4. Error Handling: Implement proper error handling and logging for webhook processing
  5. Monitoring: Monitor webhook delivery success rates and processing times

Support

For questions or issues related to webhooks, please contact Spidr support or refer to the main API documentation.

Updated about 3 hours ago

Did this page help you?