Webhooks Overview

Webhooks (also called Publish Notifications, or PNs) are how the BaaS platform delivers real-time event notifications to your system. Rather than polling for state changes, you register an HTTPS endpoint and Green Dot POSTs a structured payload to it whenever a relevant event occurs — a card transaction, an account status change, an ACH update, and so on.

Your endpoint is configured per event type, so you can route different event categories to different services, or fan them all into a single handler. Either approach is valid.

How It Works

1. An event occurs on the platform (e.g., a POS authorization, an account status change).
2. The BaaS platform constructs a webhook payload and POSTs it to your pre-configured endpoint over HTTPS.
3. Your endpoint processes the payload and responds with HTTP 200 or 201 and a valid JSON body (see Response Format below).
4. Green Dot logs the result. Non-2xx responses trigger the retry logic described below.

PCI note: Webhook payloads never include full PANs, CVVs, PINs, or expiration dates. Only the BIN and last 4 digits of the PAN are included.

Outbound HTTP Headers

Every webhook request from Green Dot includes these headers:

Authentication

Before posting a webhook, Green Dot authenticates to your endpoint. The following authentication types are supported:

• OAuth — Standard client credentials flow
• FormOAuth — OAuth over form-encoded body
• PartnerOAuth — Partner-managed OAuth
• FormUrlEncodedOAuth — URL-encoded form variant
• Certificate — Mutual TLS (mTLS)

API keys for PIE (test) and Production environments must be provided to Green Dot via a secure channel.

Example: OAuth token request

curl --location 'https://bank-events.XXXXX.com/api/v1/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=CLIENTID' \
  --data-urlencode 'client_secret=SECRET' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=post:webhook'

Example response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "post:webhook"
}

Event Types

The platform emits webhooks for the following event categories:

Multi-clearing transactions: A single webhook can contain multiple events (one per clearing) in the same POST body.

Response Format

Your endpoint must respond with HTTP 200 or 201 and a JSON body. Use the response body to return a correlation ID — this helps Green Dot's support team trace issues on your end.

Required response headers

Echo back the x-GD-RequestId header that Green Dot sent in the request.

Example response

{
  "responseDetails": [
    {
      "code": 0,
      "description": "80172fdd-012f-4635-bb4f-dd71a637cc92",
      "subCode": 0
    }
  ]
}

Response Code Reference

Retry Behavior

This feature must be explicitly requested and configured per partner.

When enabled, failed webhook deliveries are automatically retried on a scheduled basis (initially hourly, for up to 24 hours) until they succeed or all attempts are exhausted.

What triggers a retry:

• HTTP 5xx response
• Request timeout
• HTTP 401 or 403 (retried once the underlying auth issue is resolved)
• HTTP 0 / hard failures: DNS resolution failure, connection failure, SSL errors

Configuration note: Retry behavior is tied to release boundaries — it cannot be toggled on/off outside of a release cycle. Async retry is available for all webhook types.

Webhook Reconciliation Files

Contact your Green Dot Representative to request this feature.

Partners configured for reconciliation receive a daily file via SFTP each morning containing all transaction webhooks sent the previous day. This enables you to verify delivery completeness and catch any gaps.

File format: CSV, PGP-encrypted before drop. You'll need the appropriate decryption keys configured in advance.

SFTP access: Green Dot provisions a partner-specific SFTP account on its server. Coordinate with your Green Dot Representative to get credentials.

Reconciliation File Fields

The file has a human-readable header row (ignorable) followed by fixed-width records.