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

User Webhooks
Account Webhooks
ACH Account Webhooks
Card Webhooks
Transaction Webhooks
ZTM Webhooks
Common Webhook Fields
Webhook Delivery
Best Practices
Support

User Webhooks

user.edit

Description: The user.edit webhook contains details about changes that were made to a user's personal information. It will provide both the new and old values for any fields that were changed. User details can be updated via API or SST.

Triggers:

Successful API call to the Edit User endpoint (PATCH /v1/user/{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",
  "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"
    }
  ]
}

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, and optional ZTM (Zero Touch Monitoring) data if applicable.

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",
  "actionRequestor": {
    "source": "api"
  }
}

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., ACH transfers, card controls). 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.achTransfers",
      "oldValue": true,
      "newValue": false
    }
  ]
}

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": "u0v1w2x3-y4z5-4a6b-7c8d-9e0f1g2h3i4j",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "x082yz13z90y844780yz5w2w66y6403v",
  "responseBody": {
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "cardId": "68950ab9h087e812g34g466c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "card.pinChanged",
  "actionRequestor": {
    "source": "api"
  },
  "changes": [
    {
      "field": "lastUpdatedAt",
      "oldValue": "2025-10-22T10:15:00.000Z",
      "newValue": "2025-10-23T15:30:00.000Z"
    }
  ]
}

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"
  }
}

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.adj

Description: The transaction.adj webhook is sent when an adjustment transaction (credit or debit) is successfully applied to an account. Adjustments are typically used for corrections or manual balance modifications.

Triggers:

Successful API call to the Create Adjustment endpoint (POST /v1/transaction/createAdjustment)
Adjustment created via the appropriate SST role

Example Payload:

{
  "uuid": "z5a6b7c8-d9e0-4f1g-2h3i-4j5k6l7m8n9o",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "ADJUSTMENT_c537de68e45d399235de0b7b11d1958a",
  "responseBody": {
    "status": "success",
    "oldBalance": 1000.0,
    "newBalance": 1050.0,
    "adjustmentTransactionId": "ADJUSTMENT_c537de68e45d399235de0b7b11d1958a",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "transaction.adj",
  "adjustmentType": "courtesy_credit",
  "creditDebitIndicator": "credit",
  "description": "Customer service courtesy credit",
  "amount": 50.0,
  "actionRequestor": {
    "source": "sst",
    "sstRequestorUserId": "admin123",
    "sstRequestorUserEmail": "[email protected]"
  }
}

transaction.payment

Description: The transaction.payment webhook is sent when a payment transaction is successfully processed. Payments are typically used for loan or bill payments associated with the account.

Triggers:

Successful API call to the Create Payment endpoint (POST /v1/transaction/createPayment)
Payment created via the appropriate SST role

Example Payload:

{
  "uuid": "a6b7c8d9-e0f1-4g2h-3i4j-5k6l7m8n9o0p",
  "companyId": "6823a83c643d753f0f79a7ec",
  "requestId": "PAYMENT_d648ef79f56e400346ef1c8c22e2069b",
  "responseBody": {
    "status": "success",
    "oldBalance": 1000.0,
    "newBalance": 850.0,
    "paymentTransactionId": "PAYMENT_d648ef79f56e400346ef1c8c22e2069b",
    "spidrActionId": "68950786e754b589d01d1339"
  },
  "spidrActionId": "68950786e754b589d01d1339",
  "accountId": "68950897f865c690e12e244a",
  "userId": "68950761e754b589d02d133c",
  "productId": "67f2a93d743e864g1g80b8fd",
  "webhookType": "transaction.payment",
  "paymentType": "loan_payment",
  "amount": 150.0,
  "actionRequestor": {
    "source": "api"
  }
}

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"
  }
}

ZTM Webhooks

ZTM (Zero Touch Monitoring) webhooks are generated by the Spidr ZTM service to provide updates on identity verification sessions and watchlist screening statuses. These webhooks are delivered automatically when certain events occur in the identity verification or AML screening workflows.

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",
  "userId": "68950761e754b589d02d133c",
  "webhookType": "user.cipStatusUpdate",
  "cipStatus": "pass",
  "spidrActionId": "68950786e754b589d01d1339"
}

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

All webhooks share the following common fields:

Field	Type	Description
`uuid`	string	Unique identifier for the webhook event
`companyId`	string	The company ID associated with the action
`requestId`	string	The request ID that triggered this webhook
`responseBody`	object	The response body from the original API call
`spidrActionId`	string	The ID of the SpidrAction that triggered this webhook
`userId`	string	The ID of the user associated with the action
`webhookType`	string	The type of webhook (e.g., "user.edit", "account.create")
`actionRequestor`	object	Information about who/what initiated the action

ActionRequestor Object

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

Field	Type	Description
`source`	string	Either "api" or "sst" indicating the source of the request
`sstRequestorUserId`	string (optional)	If source is "sst", the user ID of the SST user who made the request
`sstRequestorUserEmail`	string (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:

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

Best Practices

Idempotency: Always check the uuid field to ensure you don't process the same webhook twice
Validation: Verify the webhook signature to ensure it came from Spidr
Async Processing: Return a 200 OK response quickly and process the webhook asynchronously
Error Handling: Implement proper error handling and logging for webhook processing
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.

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

user.create

user.archive

user.retrieveId

user.retrieveIdHistory

Account Webhooks

account.create

account.shippingAddressUpdate

account.statusUpdate

account.featureUpdate

ACH Account Webhooks

achAccount.create

achAccount.remove

Card Webhooks

card.activate

card.frozen

card.unfrozen

card.replaced

card.reissued

card.resetPin

card.mobileWalletProvision

card.fetchImageUrl

card.pinToken

card.pinChanged

card.statusUpdate

Transaction Webhooks

transaction.createAch

transaction.createFee

transaction.reverseFee

transaction.adj

transaction.payment

transaction.a2a

transaction.cancelAch

ZTM Webhooks

idvSession.manualReviewRequired

idvSession.needsDecision

idvSession.retry

idvSession.rerun

idvSession.stale

watchlistScreening.statusUpdate

watchlistScreening.hitUpdate

user.cipStatusUpdate

Common Webhook Fields

ActionRequestor Object

Webhook Delivery

Best Practices

Support