Webhooks
Account creation webhooks
As an account moves through the underwriting and boarding process, our servers will perform an HTTPS POST to your endpoint with data concerning the status of the account. These notifications allow you to take action or make any appropriate updates within your app.
Receiving Webhooks
As part of account setup, you will be asked to provide an HTTPS endpoint where we can direct webhooks. In order to receive these webhooks, your endpoint will need to be publicly accessible. All webhooks will contain a token (your API key) in the JSON body that you can use to verify the authenticity of the request.
There are 6 different account statuses that will trigger a webhook being sent to your endpoint: processing
, declined
, boarded
, deployed
, and active
. The request body of each webhook will contain a JSON object with some common attributes and, depending on the status, some special attributes pertaining to that status. Details on the meaning of each attribute and status are outlined below.
Request Body
{"id":"APP-101","status":"processing","eventTime":1520404796828,"token":"{your API key here}"}
This is an example of a request body for a “processing” status, which has no special attributes. The attributes it contains, which comprise the attributes common to all statuses, are:
id
string
The identification number of the account to which this webhook notification pertains. This corresponds to the
applicationId
in the success response body of an account creation request (POST to/application
).
status
string
The account status being reported. The value will be one of:
processing
,declined
,boarded
,deployed
, andactive
. For the significance of each status, see the relevant section below.
eventTime
integer
A timestamp of the actual time when the status event occurred, represented as milliseconds since January 1, 1970 00:00:00 GMT.
token
string
Your API key, which acts as a unique identifier for your API account that you can use to verify the authenticity of the request.
Webhook Token Verification
When you are given your API access credentials, you will also receive an API key, which is the same value that will be sent in the token
attribute of every webhook request body. To protect against spoofing, we recommend that you always check for a matching token value on any incoming traffic to your endpoint. If the token value is missing or doesn’t match, the request did not originate from Gravity Payments and should be discarded.
Expected Response
To indicate that a webhook has been received, you will need to respond with an HTTP status code of 200. In the body of the response should be only the word “gravity” (without quotes). Responding with this keyword will signal that the webhook has not only been received, but successfully recorded/processed.
Example:
HTTP/1.1 200 OK
...
gravity
Delivery Schedule
When a status update occurs, a webhook will be sent in near real time. If the webhook request does not get the expected response—for instance if your endpoint has an outage—our server will attempt to re-deliver the webhook over a period of a couple days until the response is received. In such a case, you may receive webhook notifications out of order, and will need to reference the eventTime
attribute to determine when each status update occurred.
Code Example
import express from 'express';
const app = express().use([
express.json(),
express.urlencoded({ extended: true })
]);
const port = 3000;
app.post('/account/webhook/listener', (req, res) => {
console.log(`Received Account API webhook with submission status: ${req.body.status}`);
res.sendStatus(200);
});
app.listen(port, () => {
console.log(`Example app listening on port ${port}`);
});
Processing Status
The processing
status indicates that an account has been accepted and is currently being underwritten. The webhook notification for this status contains no special attributes. Below is an example:
{"id":"APP-102","status":"processing","eventTime":1521062626702,"token":"{your API key here}"}
Declined Status
If, for some reason, the submitted account is unable to be underwritten, then it will move to a “declined” status. This would happen if, for instance, the merchant presents an unreasonable processing risk, such as dealings in a restricted industry or a history of excessive chargebacks. Upon declining underwriting of the account, a declined
webhook will fire. This webhook contains no special attributes.
Example:
{"id":"APP-102","status":"declined","eventTime":1521062626702,"token":"{your API key here}"}
Boarded Status
Once an account has been underwritten, it gets boarded onto Gravity’s processing platform and the boarded
webhook is fired. Example below:
{"id":"APP-102","status":"boarded","eventTime":1521062626702,"token":"{your API key here}","mid":"517924510026974"}
This status update carries the special mid
attribute.
mid
string
The Merchant Identification Number for this account.
The Merchant Identification Number, or MID, is essentially the merchant’s account number for their processing account with Gravity. It is the number that appears on all processing statements, and that the merchant can use to identify their account to Customer Support. The MID is what you’ll want to present to the merchant as their account number, while the id
is kept for internal reference of the submitted account.
Deployed Status
With the account boarded for processing, any products ordered can now be deployed. For physical products, such as terminals and card readers, this means they’ve been programmed and shipped.
Here’s an example of the webhook:
{"id":"APP-102","status":"deployed","eventTime":1521062626702,"token":"{your API key here}"}
When an account reaches “deployed” status, it is ready for processing. Therefore, once a device is received or gateway access obtained, it can be used immediately to process transactions.
Active Status
This status signifies that an account has begun processing transactions. The first time that a batch settles containing one or more transactions in the amount of $5 or more, this status is triggered. The webhook that gets sent has no special attributes.
Example:
{"id":"APP-102","status":"active","eventTime":1521062626702,"token":"{your API key here}"}
Monitoring for Activity
Oftentimes integration partners want to know that the merchants they’re setting up are beginning to use their accounts. Otherwise, it may indicate that the merchant has hit a roadblock or doesn’t understand how to use the product. The active
webhook provides the update you need in order to monitor your accounts in the critical starting stage.