Support for Legacy Callback Code

Working with pre-existing code

Using the Ping / Callback API from legacy code that only supports HTTP GET requests.

In many legacy code bases, callback URLs are typically expected to require invocation via the HTTP GET method because this was a common convention in earlier web development practices.

The HTTP GET method is used to request a resource from a web server, such as a web page or an image file, by sending a request to a specific URL. GET requests are considered “idempotent,” meaning that they can be repeated without changing the state of the server or the resource being requested. This makes them a good fit for callback URLs, which are typically used to send a notification or a response to a server without changing the server’s state.

In the early days of web development, callback URLs were often used to send notifications or responses from a third-party service, such as a payment gateway or a social media platform, back to the server hosting the application. Because these notifications or responses were typically short and did not require any additional data to be sent to the server, the HTTP GET method was a convenient choice.

To ease integration with these kinds of environments, we provide a special case proxy that operates as per the following diagram.

sequenceDiagram %%{init: { 'theme':'base', 'themeVariables': { 'primaryColor': '#BB2528', 'primaryTextColor': '#000', 'primaryBorderColor': '#7C0000', 'lineColor': '#F8B229', 'secondaryColor': '#006100', 'tertiaryColor': '#000', 'fontFamily': 'Raleway, Verdana, Arial', 'fontSize': '30px' } } }%% participant client as Client participant proxy as API Gateway participant back as Backend client->>proxy: GET /legacy/notify?api_key=⋯ proxy->>back: POST X-API-Key + payload back->>proxy: API Response + payload proxy->>client: API Response + payload

This arrangement allows API users to employ a simple HTTP GET request to issue a ping notification through this API. HTTP requests must be directed to the /legacy/notification endpoint, present in both the production and sandbox environments.

API key requirements and whitelisting considerations still fully apply.

The following is an example of invoking this legacy API method using the curl command line tool.

$ curl "https://sandbox.ping.api.crediterium.net/legacy/notification?api_key=9fd7ef8f-8d09-466a-95c4-dddd865a7e9b&action=completed&outcome=success&transaction_id=foobar&revenue=1.42" \
  --header "Content-Type: application/json" \

HTTP/1.1 201 Created
Server: nginx/1.14.2
Date: Mon, 27 Mar 2023 00:57:55 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Content-Range: */*
Content-Location: /legacy/notification

The /legacy/notification endpoint will always connect to the latest version of the /notification endpoint provided by the API.

Back to our APIs