FFL360 allows you to configure webhooks on the store level. You can find the secrets and other webhook details under Admin section inside FFL 360.

Configuring Webhooks

Requirements

You can set a public endpoint in the webhook section. You endpoint must meet the following requirements:

It should support HTTP POST method.
The webhook call must be completed within 20 seconds.
It must return a HTTP response status 204 for success, any other status is considered as failure.

Payload

The payload of the webhook is in JSON format and an example is given below. Exact payload details depends on your product license.

{
  "dealer": {
    "preferredShippingAddress": {
      "street": "595 Market St",
      "city": "San Francisco",
      "state": "CA",
      "zipCode": "94105",
      "preferredAddressType": "mailingAddress", // 
      "RBDI": "commercial" // This field is subject to license agreement
    },
    "contact": {
      "name": "Jon Doe",
      "email": "",
      "primaryPhoneNumber": ""
    },
    "businessName": "CHATTAHOOCHEE MUNITIONS, LLC",
    "CFD": "67252", // This field is subject to license agreement
    "fflLicenseNumber": "1-58-121-07-8H-22932",
    "abbreviatedFFLNumber": "1-58-22932",
    "fflExpirationDate": "08/01/2028",
    "EIN": "451554762", // This field is subject to license agreement
    "FFLLicenseType": "07",
    "SOTOperationType": "62",
		"SOTClass":"Class 2",
    "isNFA-SOTOnFile": true
  },
  "transfer": {
     "transferId": 19338,
     "orderId": "17330",
     "source": "E-commerce",
     "status": "ready",
     "transferProof": "https://documents.masterffl.com/proofs/17330.pdf", // This field is subject to license agreement
      "transferSellerPacket": "https://documents.masterffl.com/ffl-transfer-proofs/d808733f-e160-4a90-8478-66d966b67901/223009/7e3902b0-0fe1-4ffa-b9a8-33f05f8505d5/transfer_seller_packet_17330.pdf", // This field is subject to license agreement
     "isDealerReassigned": false
   }
}

Authorization

To prevent and unauthorized invocations, FFL360 attaches signature to every webhook invocation. Clients should verify the signature and process the request only if signature is matched.

The signature is sent under header: x-signature

Clients can match the signature by recomputing the signature using HMAC algorithm. Please look at the sample code for your platform:

import crypto from "crypto";

const signatureHeader = req.headers["x-signature"]; //example: sha256=xxxxxxxxxxxxxxxxxxx

const computedSignature = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");


const valid = crypto.timingSafeEqual(
    Buffer.from(signatureHeader.split("=")[1]),
    Buffer.from(computedSignature)
);

if (!valid) {
    console.warn("Signature could not be matched");
    return res.status(401).send("Signature mismatch");
  }

//The signature is matched, you can process it!

//Finally return the success response
return res.status(204)

Backward Compatibility

Failover and Retries

After invoking the webhook, if FFL360 does not get a success response within 20 seconds, it is considered as a failed attempt. FFL360 will attempt to invoke the webhook 2 more times, and if these 2 subsequent attempts also fail, then the webhook is never called again for that transfer.

Furthermore, if we are not able to call webhook successfully for 5 transfers in a row, the webhooks are automatically disabled for security reasons. You can enable it back once you troubleshoot and resolve the issues.