Webhooks

Webhooks provide a powerful way to stay in the loop on what’s happening in your card program. We use webhooks to notify you when events occur so that you can take appropriate actions.

Apto has APIs, so why would you use webhooks? With an API, you initiate. You ask us to create, delete, update, or send you data. With a webhook, Apto initiates. When events happen in our system, we send data to you about those events.

Before you start using webhooks, decide which events you want to know about. Not every event is useful to every Apto customer. Listening for events that you don’t need is a bad idea. It can put an unnecessary load on your servers. See the list of available webhook events.

Here are some examples of how to map business actions to webhook events:

  • You might want to inform each cardholder when a card is on its way. To do that, you’d listen for the card_sent event to find out when a new card has been created and mailed out.
  • If you are managing a user’s funding account yourself, you would credit or debit the account when a transaction amount has been updated. To do that, you’d listen for the transaction_update event.

After identifying which events to listen for, you’ll create webhook endpoints on your server. These endpoints are where Apto sends the webhook event data so that you can take action.

Available webhook events

You can subscribe to any of the provided Apto webhook events, and can provide different endpoints for each subscription. We can also send an event to more than one endpoint, if needed.

We support the following events:

Card

Event typeEvent is sent when...
status_updatea card’s status is updated
pin_updatea card’s PIN is updated
card_senta card is reported as having been shipped
card_batch_updatea card batch’s status is updated
card_updatea card is updated, but the update is not accounted for by another webhook

User

Event typeEvent is sent when...
kyc_updatea user’s kyc_status is updated
identity_updatea user’s identity details are updated, such as name, email address, or phone number
user_updatea user is updated, but the update is not accounted for by another webhook

Transaction

Event typeEvent is sent when...
transaction_updatea transaction is updated

Receiving webhooks

Creating a webhook endpoint on your server is no different from creating any page on your website. If you are using a Ruby framework such as Sinatra, you add a new route with the desired URL. If you’re using PHP, you create a new .php file on your server.

Apto makes an HTTP POST request to send the Event object to your endpoint URLs. Set up your webhook endpoints to receive and process JSON payloads. We deliver webhook data as JSON in the POST request body.

When you receive webhooks, you must acknowledge receipt. This is done by providing the HTTP status code 200 OK. Due to the asynchronous nature of webhooks, events may be sent out of order if we do not get a 200 OK status code. You can use the event id and created_at attributes to help manage duplicates and notifications coming in the wrong order.

When you are ready to process webhooks, open the Apto developer dashboard, navigate to Developers, open the Webhooks tab, and select Add endpoint. Enter your endpoint URL, select events for Apto to send, and select Create.

Retry logic

When you receive an event, your endpoint must return a 2XX HTTP status code. It is important that you acknowledge the receipt of events prior to taking any action following their receipt in order to prevent timeouts. Any response codes outside of the 2XX HTTP range, such as 3XX codes, indicate that you did not receive the event.

If we do not receive a 2XX code, we will retry every two hours for up to 48 hours. After 24 attempts without receiving a 2XX status code, the event fails.

Authenticating webhooks

Webhooks are sent using basic auth headers as the authentication scheme. When creating an endpoint, you will provide us with the basic auth username and password that we should use when sending you these events.

Event object

The Event object contains full event details, which you can use after parsing the JSON into an Event object.

Here are some of the included fields:

  • The event id is unique across all events. This value should be used to determine idempotency. If you see an event ID twice, Apto likely did not receive a 200 OK receipt for the original event.
  • The event created_at value is the timestamp of when this event occurred. This value is important because events for the same object may potentially arrive out of order.
  • Each event also has a type. For the full list of event types, see available webhook events.

For details on data present in the webhook event body, see Events in the Apto API documentation.

Webhook testing

Apto can keep logs of all the URLs that we ping, and provide these to you to reconcile against those received. Please contact our developer support to access this request history.

Please bear in mind that it is important to consider capacity planning when testing your webhooks, as there is the possibility that a significant number are sent which could overload your servers.