Introduction

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.

📘

Note

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

Headers

Webhook Body

"Webhook Data" Object

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

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.