Webhooks

Webhooks allow services to notify each other of events. At their core they are as simple as a POST request to a predefined API endpoint. You can configure any API endpoint you’d like within the Merchant Portal.

We recommend you use one endpoint per service which listens to all types of events.

For example, if you receive webhooks from Acme Inc., you may structure your API endpoint URL like so: https://www.example.com/acme/webhooks/.

You can indicate that a webhook has been successfully processed by responding with a 2XX HTTP status code (200-299). We recommend disabling CSRF protection for this endpoint to ensure proper processing.

Please be sure to verify the signature and timestamp when processing webhook requests. You can learn more about this in the webhook signature verification page.

Events types

Ansa supports several event types that you can subscribe to. One such event type is autoreload.success. Below is a sample payload for autoreload.success:

{
  "customer_id": "811233AE-ED61-4C52-A729-754B7396D0A3",
  "data": {
    "current_balance": {
      "amount": 2000,
      "currency": "usd"
    },
    "event_created_timestamp": "2023-08-01T12:34:56.123Z",
    "reload_amount": 500,
    "transaction_id": "46B5C79C-84AE-4175-8AFD-0A6D0AF7368F"
  },
  "error": null,
  "id": "EAF61643-5B8D-4E8C-84B6-60D29D4CCA27",
  "merchant_id": "E3C103D6-2BD2-4E30-9B1F-D6EF4E5699B4",
  "type": "autoreload.success",
  "version": "v2"
}

Ansa webhook payloads will generally adhere to the following structure:

{
  "customer_id": "<uuid>",
  "data": {},
  "error": {
    "code": "error code string",
    "message": "error message string",
    "type": "error type string"
  },
  "id": "<uuid>",
  "merchant_id": "<uuid>",
  "type": "type name",
  "version": "v2"
}

Please refer to Ansa’s Webhook Event Types catalog for the full list of supported event types, their payload structure, and description.

Adding an endpoint

In order to subscribe to Ansa webhooks, you will need to configure your endpoints. You can do this in the Merchant Portal webhooks settings page.

Adding an endpoint is as simple as specifying the URL for your API endpoint and optionally selecting a subset of event types that you want to subscribe to.

If you don't specify any event types, by default, your endpoint will receive all events, regardless of type. This can be helpful for getting started and for testing, but we recommend specifying the subset of event types you care about to avoid receiving unnecessary API requests.

📘

Don't have a webhook API endpoint?

If your service isn’t ready to start receiving webhook requests, you can use Svix Play to generate a unique URL and add this endpoint in the Merchant Portal webhooks settings page.

This will allow you to inspect webhook request payloads for the events that you’ve subscribed to.

Testing your endpoint

The Merchant Portal webhooks settings page has a Testing tab which allows you to send example events to your endpoint. This Testing tab can help you detect issues with your API endpoint implementation or configuration and fix them before they make it to production.

After sending an example event, you can inspect the message payload and view the status of message attempts.

IP whitelist

In case your webhook receiving endpoint is behind a firewall or NAT, you may need to allow traffic from Ansa's webhook IP addresses.

This is the full list of IP addresses that webhooks may originate from:

44.228.126.217
50.112.21.217
52.24.126.164
54.148.139.208

Webhook message persistence

Webhook messages are stored for a maximum of 60 days and then deleted.