Webhooks are event notifications sent between Netspend and partners.

Netspend uses “outgoing” (outbound) webhooks to push event notifications to a partner for relevant information about the partner or their managed customers.



Netspend also offers an “incoming” event option by way of an account-level “events” endpoint that allows partners to inform Netspend systems about account level events happening in their systems to help synchronize data and assess risk. See Account Overview for details.

This topic focuses on outgoing event notifications.

Sample Flows

Outbound Webhooks to Partner

This diagram shows an example flow where a P2P transfer expires out of band of any direct requests to the Netspend API, resulting in a p2p_transfer.expired webhook. The original pending transfer triggers a webhook notification as well.

Outbound Webhook Event Notifications

For webhooks event notifications from Netspend to the partner:

  • Set up:

    • The partner needs to set up a server with an endpoint listening for webhook events.
    • The partner communicates the URL for that endpoint to Netspend.
    • Netspend generates an HMAC key to be shared with the partner. Will be used to verify the integrity of the webhook bodies received.
  • Partner server responses:

    • Partners are required to respond to all event messages with an HTTP 200 response.
    • Any other HTTP response code or 10 second response timeout will trigger the message to be redelivered. The Netspend webhook sender does not honor any HTTP 3xx messages as redirects, and instead schedules them for redelivery the same as with other non-200 responses.
  • Redelivery:

    • When a message is scheduled for redelivery, Netspend makes several attempts to redeliver it over the next 72 hours, using an exponential backoff algorithm.
    • With each subsequent attempt, the only difference in the message is the incrementing of the ns-delivery-count header value.
    • Netspend retains messages for some amount of time for diagnostics, but does not guarantee the data retention of messages that have been delivered or failed redeliveries past 72 hours.
    • Netspend does not currently support requests to replay failed event messages.
  • Non-sequential delivery:

    • Due to the possibility that any individual Event message can fail during an initial delivery attempt, partners are expected to handle event messages being delivered out of order.
    • A partner may receive the second message for a resource before the first, and therefore they must use the ns-first-delivery header and timestamp property to determine whether the information about a given resource is older than the data already at the partner's system.
  • Network Level Security

    • Webhook notifications use HTTPS with TLS 1.2 for all requests.
    • Mutual TLS and older versions of TLS or SSL are not supported.
    • The partner's servers need to issue publicly-signed certificates to Netspend for production usage.
    • Self-signed certificates are supported for the test environment.
  • No Self-Service Subscriptions

    • The Netspend API does not expose any self-service endpoints to create, view or manage webhooks subscriptions.
    • All configurations must be made by Netspend personnel on the partners' behalf.
    • All webhooks for the partner will be sent to a single endpoint on a server managed by the partner.

Outbound Webhook Event Notification Structure


ns-delivery-countIntegerThe inclusive number of times the webhook has been sent, starting with "1." Partners may choose to use this header to determine if a message is a redelivery. Values above 1 imply that an acknowledgment had not been received on prior sends.2
ns-first-sentString, date timeThe time when the webhook was first sent. Subsequent retries do not modify this header value. If the webhook is particularly old, the partner may want to call directly to the Netspend API to verify the current correctness of the data.2019-09-01T12:34:56Z
ns-webhook-signatureStringAn HMAC calculation on the body of the webhook. Subsequent retries do not modify this header value. Since this event authentication is the primary means of asserting the Netspend's identity, partners are required to verify the HMAC hash of every webhook they receive. For any message that does not pass this validation, the partner is expected to ignore the webhook, and potentially to escalate to the Netspend partner integration team if they suspect the underlying hashing secret has been lost or compromised.yUlUBKByT6m4SOl4T64PrU0azZE=

Webhook Body

typeString, one of:
• account.blocked
• account.closed
• account.created
• account.unblocked
• account.first_funded
• account.overdraft.activated
• account.overdraft.deactivated
• account.overdraft.enrolled
• account.overdraft.grace_period.modified
• account.overdraft.incurred
• account.savings.closed
• account.savings.eligible
• automatic_savings_transfer.failed.savings
• automatic_savings_transfer.preference.added
• automatic_savings_transfer.preference.removed
• automatic_savings_transfer.failed.insufficient_balance
• automatic_savings_transfer.failed.savings_blocked
• card.activated
• card.expired
• card.locked
• card.ordered
• card.shipped
• card.unlocked
• account.external_bank_transfer.deposit.completed
• account.external_bank_transfer.deposit.failed
• account.external_bank_transfer.deposit.pending
• account.external_bank_transfer.deposit.reversed
• account.external_bank_transfer.withdrawal.completed
• account.external_bank_transfer.withdrawal.failed
• account.external_bank_transfer.withdrawal.pending
• account.external_bank_transfer.withdrawal.reversed
• p2p_transfer.completed
• p2p_transfer.failed
• p2p_transfer.pended
• person.kyc.identity_scan.modified
• person.kyc.modified
• person.modified
• person.ofac.failed
• person.ofac.modified
• person.removed
• document_request.created
• document_request.completed
• documentRequestCompletedWebhook
• account.external_card_withdrawal.completed
• transaction.completed
• transaction.partially_settled
• transaction.pended
• transaction.released
The type of the data associated with the webhook type. It is possible, but unusual, to have more than one data object for a given webhook.(see example below)
idString, UUIDUnique ID for the webhook itself.(see example below)
timestampString, date timeThe time this particular webhook was sent.(see example below)
dataArray of “Webhook Data” objects (see below)Data objects associated with the webhook.(see example below)

"Webhook Data" Object

typeString, one of:
• account
• account_balance
• card
• document_request
• external_bank_transfer_deposit
• external_bank_transfer_withdrawal
• external_card
• overdraft
• p2p_transfer
• person
• savings
• transaction
The type of the data associated with the webhook type. It is possible, but unusual, to have more than one data object for a given webhook.(see example below)
refString, URLURL pointing to the call to get the resource related to the given webhook type. E.g. a “card.activated” webhook would return the URL to get the card that was activated.(see example below)
payloadJSON objectThis is the JSON object, from the main Netspend API specification, that is returned from calling the “ref” URL. Represents the state of that object at the time the webhook occurred.(see example below)

Example Webhook Body

  "type": "card.activated",
  "id": "3c1cab9d-10f5-42fd-8662-99d2755b3d87",
  "timestamp": "2019-09-01T12:34:56Z",
  "data": [
      "type": "card",
      "ref": "https://api.netspend.com/v1/cards/3c1cab9d-10f5-42fd-8662-99d2755b3d87",
      "payload": {
        "id": "51f356ba-8fe2-40de-b6ad-d19444020090",
        "account_id": "3c1cab9d-10f5-42fd-8662-99d2755b3d87",
        "person_id": "45cb8175-c2c1-4695-ade7-051f342237ae",
        "brand_name": "GPR_BLUE_CARD",
        "pan_last_4": "9012",
        "expiration_month": 11,
        "expiration_year": 2024,
        "type": "physical",
        "status": "active",
        "status_reason": "expired",
        "lock": {
          "status": "locked",
          "unlock_time": "2019-09-01T12:30:00Z"
        "shipping": {
          "status": "shipped",
          "shipment_date": "2019-07-02",
          "estimated_arrival_date": "2019-07-12",
          "tracking_number": "123456789012",
          "shipping_vendor": "Fedex"

Data Endpoints Corresponding to Outbound Payloads

Webhook Data Payload TypeNetspend API Data Endpoint Signature
accountGET /accounts/{account_id}
account_balanceGET /accounts/{account_id}/balances
cardGET /cards/{card_id}
document_requestGET /document_requests/{request_id}
external_bank_transfer_depositGET /accounts/{account_id}/external_bank_transfers/deposits/{deposit_id}
external_bank_transfer_withdrawalGET /accounts/{account_id}/external_bank_transfers/withdrawals/{withdrawal_id}
external_cardGET /accounts/{account_id}/external_card_withdrawals/{withdrawal_id
overdraftGET /accounts/{account_id}/overdraft
personGET /people/{person_id}
savingsGET /accounts/{account_id}/savings
savings_transfer_perferenceGET /accounts/{account_id}/savings/automatic_transfers/{transfer_id}
transactionGET /transactions/{transaction_id}

Outbound Webhook Event Notification Example Scenarios

There are a number of different scenarios where webhooks are sent from Netspend systems to the partner, which may or may not be accompanied by email notifications as well. The partner’s use of these notifications is determined based on the context of what action the card holder has performed and the method of how these notifications are delivered.

An example is the notification of the expiration of a P2P transfer, where the prospective receiver of funds took too long to respond to the transfer request from the sender. The expiration happens out of band, and is not part of in-line flows. In this scenario, a webhook and an email notification are both sent.

Some scenarios that do not result in webhook notifications, but rather alternative notifications like email, are included for comparison purposes.

An account has been opened with KYC status approved• Netspend webhook: account.created
• Netspend email to card holder
OFAC failure during activation/account creation• Netspend webhook: person.ofac.failed
An account holder contacts customer service to make a change to KYC data such as SSN or DOB• Netspend webhook: person.modified
An account is blocked by customer service after a negative risk assessment report• Netspend webhook: account.blocked
• Netspend email to card holder
An account is closed by customer service after discovery of evidence of fraud• Netspend webhook: account.closed
• Netspend email to card holder
An account holder contacts customer service to change address on file• Netspend webhook: account.modified
• Netspend email to card holder
The terms for an account have changed• (No Netspend webhook)
• Netspend email to card holder
An account acquisition flow leads to a KYC conditional or rejected state, and customer service progresses to requiring documents.• (No Netspend webhook)
• Netspend email to card holder requesting documents
Card is ordered through partner application• Netspend webhook: card.ordered
• Netspend email to card holder
Card ordered by person is shipped• Netspend webhook: card.shipped
Account holder receives card and activates it through partner application• Netspend webhook: card.activated
Card expires• Netspend webhook: card.expired
An account holder’s card is locked by customer service after negative risk assessment feedback• Netspend webhook: card.locked
An account holder’s card is locked by customer service after resolving issues from negative risk assessments• Netspend webhook: card.unlocked