Using Webhooks


Webhooks are postback messages that Forte sends to unique, server-side URL endpoints, which you define. You can then use these messages to verify information and perform tasks in your own system, such as

Webhook messages are triggered by transaction events. An event is simply an action that occurs during the progression of the transaction (i.e., from capture to processing). For example, when you use Forte's REST API to create a saletransaction, three events occur: transaction.sale, customer.create, and paymethod.create. You can configure your webhooks to capture all the events of a transaction under a common event ID (e.g., evt_xxxxxx) or configure different webhooks to capture different combinations of events. This is referred to as subscribing to events. NOTE: Depending on how you configure your event subscriptions, the same data may be generated twice in separate webhooks. For example, a POST to the customer object that includes the creation of a paymethod could (if subscribed) generate a customer webhook with both customer and paymethod data as well as a paymethod webhook.

In the example described above, three events occur from a single sale transaction. To make managing the data easier, you could subscribe a single webhook to all three events, or create one webhook that captures customer and paymethod events and one webhook that captures transaction events. Each webhook could be used to connect to different information management systems (e.g., the customer/paymethod webhook could connect to a CRM application while the transaction webhook connects to an invoicing application).

Why Should I Care About Webhooks?

Webhooks send postback messages to the merchant server, which is a more reliable and secure method of verifying transactions than real-time callbacks, which post to the client-facing application. Webhooks also offer superior error handling and fraud protection capabilities. As a best practice, Forte recommends that merchants use webhooks to confirm that transaction information has posted to their accounts before fulfilling/completing the transactions (e.g., shipping merchandise to the customer). Webhooks can be used for both client-side and server-side functionality; however, webhooks can take as long as five minutes or more to post, which could result in a sluggish and less-than-desirable customer experience. If a webhook post fails (i.e., does not result in an HTTP 200 response), Forte retries the webhook up to twenty times adding one minute for each retry.

What Forte Applications Use Webhooks?

The following Forte products support webhooks.

How do I Configure Webhooks?

Up to twenty-five webhook endpoints can be configured for an organization.

Users with one of the following roles can create webhooks in Dex:

If there are no dex users in your Partner organization with one of these roles, please contact Forte Technical Support at 888-235-4635 option 5. and provide them with the following required information:


Field Description
Name The name of the webhook. The value of this field should be concise and capture what events this webhook will record (see below).
Status The status of the webhook. Use the dropdown to select the supported options: Active or Pending.
URL The secure URL endpoint where Forte will post this webhook. At a minimum, this URL should be an SSL-encrypted, dedicated page on your own server.
Events

The action(s) that will be captured by this webhook.

Object Webhook
customer
  • Create
  • Update
  • Delete
Payment
  • Create
  • Update
  • Delete
Transaction
  • Sale
  • Authorize
  • Disburse
  • Void
  • Capture
  • Inquiry
  • Verify
Schedule
  • Create
  • Update
  • Delete
Scheduleitem
  • Create
  • Update
  • Delete
Merchantapplication
  • Approved
  • Declined
  • Received
  • Pending
  • Recalled
  • Rejected

Creating the Webhook in Dex

To define your webhook, in Dex, select Developer > Webhooks from the Dex main menu and then click Create Webhook.

The following screen displays: Enter a unique Webhook name, set the status to Active or Pending, and enter the URL for your server which will receive the Webhook postbacks.

Define the events that trigger the Webhook using the Resource sections and actions, select All to receive webhooks for all resource actions, or Custom to specify which events trigger the webhook.

NOTE: Merchant application webhooks are available at the partner organization level.

How do I Authenticate Webhooks?

After providing the configuration information, Forte Technical Support will send you a unique webhook_key for each webhook endpoint you define. You'll use this value to compute the signature parameter and authenticate the webhook by comparing it to the value in the X-Forte-Signature HTTP header. A signature comparison ensures the webhook came from Forte and that no one tampered with the webhook payload.

The signature parameter is computed with a hash-based message authentication code (HMAC) using a secret key (i.e., webhook_key) and a SHA256 digest algorithm:

HMACSHA256(webhook_url|payload|utc_time, webhook_key)

Where

Parameter Description Example
webhook_url The all-lowercase webhook URL. Requires the HTTPS URI scheme to protect privacy and data integrity. https://www.mycompany.com/webhook/pay.aspx
payload The JSON contents of the webhook.

 

                                  "location_id":"loc_115161",
   "event_id":"evt_o5bgfKnXbEKmPyp06-dZ3Q",
   "paymethod":{
      "paymethod_token":"mth_jKxUPnIYTMq8iMqjp4CcsQ",
      "organization_id":"org_300005",
      "location_id":"loc_115161",
      "customer_token":"cst_9s7_JzBUT9eCnuW6Wkwcug",
      "label":"Visa Credit Card - 1111",
      "notes":"",
      "card":{
         "name_on_card":"Joey JoJo Shabadoo",
         "masked_account_number":"************1111",
         "expire_month":11,
         "expire_year":2020,
         "procurement_card":false,
         "card_type":"visa"
      },
      "links":{
         "self":"https://sandbox.forte.net/API/v3/
          paymethods/mth_jKxUPnIYTMq8iMqjp4CcsQ"
      }
   },
   "source":"RESTAPI/3",
   "type":"payment.create",
   "environment":"live"
}
                            
utc_time UTC time in ticks (since 01/01/0001 00:00:00) sent in the x-forte-utc-time header parameter. 634094514514687490
webhook_key The webhook key. This value is unique for each webhook endpoint that you define. AD6cNaWFoDla5VXqN2clfJjkGnCo6TNc

 

The following signature formula example uses values that come from the examples displayed in the parameter table above.

                HMACSHA256(https://www.mycompany.com/webhook/pay.aspx|{ "location_id":"loc_115161", "event_id":"evt_o5bgfKnXbEKmPyp06-dZ3Q", 
"paymethod":{ "paymethod_token":"mth_jKxUPnIYTMq8iMqjp4CcsQ", "organization_id":"act_300005", "location_id":"loc_115161", 
"customer_token":"cst_9s7_JzBUT9eCnuW6Wkwcug", "label":"Visa Credit Card - 1111", "notes":"", "card":{ "name_on_card":"John Smith", 
"masked_account_number":"************1111", "expire_month":11, "expire_year":2020, "procurement_card":false, "card_type":"visa" }, 
"links":{ "self":"https://sandbox.forte.net/API/v3/paymethods/mth_jKxUPnIYTMq8iMqjp4CcsQ" } }, "source":"RESTAPI/3", 
"type":"payment.create", "environment":"live" }|634094514514687490, AD6cNaWFoDla5VXqN2clfJjkGnCo6TNc)
            

 

When put through the HMACSHA256 algorithm with the webhook secret key value of AD6cNaWFoDla5VXqN2clfJjkGnCo6TNc, the formula renders the following value:

                30eaf51928aea79e67de3396578862254eeb4a8b0ae85550bdd7ae87c5708fb9
            

 

If the webhook payload is secure and the webhook can be authenticated from Forte, this signature value will match the value that is returned in the webhook's X-Forte-Signature HTTP header field:

                Accept: application/json
Content-Type: application/json
X-Request-Id: 7066f5f3-33a0-47a8-9f03-a0e94b4b2a5f
X-Forte-Utc-Tim: 634094514514687490
X-Forte-Signature: 30eaf51928aea79e67de3396578862254eeb4a8b0ae85550bdd7ae87c5708fb9
            

The following payload example displays the headers and raw body content of a sample webhook. The value of the webhook_key parameter for this example is AD6cNaWFoDla5VXqN2clfJjkGnCo6TNc and the value of the webhook_url parameter is https://www.mycompany.com/webhook/pay.aspx.

NOTE: The provided sample is merely an example and not all-inclusive of the parameters listed in the transaction object of Forte's REST API. The webhooks you receive will depend upon your webhook event configuration and the Forte application you use to create the transaction.

Headers

Copy
Accept: application/json
Content-Type: application/json
X-Request-Id: 7066f5f3-33a0-47a8-9f03-a0e94b4b2a5f
X-Forte-Utc-Time: 634094514514687490
X-Forte-Signature: 08f2c97bfe283ffa17543eeea42b84a06d0a1ed757cd12938ab50dd3ffc6e7b9

Raw Body

Copy

                {
  "location_id":115161,
  "event_id":"evt_IO-4Mw9PYEyipIgkNty2vw",
  "transaction":{
    "transaction_id":"trn_63f475e1-d468-4239-b795-cb18fcd1f698",
      "organization_id":"org_300005",
      "location_id":"loc_115161",
      "status":"ready",
      "action":"sale",
      "authorization_amount":5.42,
      "sales_tax_amount":0.42,
      "service_fee_amount":0.0,
      "authorization_code":"123456",
      "entered_by":"m1NrGv9pM",
      "received_date":"2015-11-02T11:49:25.69",
      "billing_address":{
        "company_name":"SmithCo",
        "physical_address":{
          "street_line1":"500 W. Bethany Drive",
          "locality":"Allen",
          "region":"TX",
          "postal_code":"75013"
        }
      },
      "card":{
        "name_on_card":"name",
        "masked_account_number":"****0006",
        "expire_month":9,
        "expire_year":2020,
        "cvv_result":"M",
        "card_type":"visa"
     },
     "response":{
       "response_type":"A",
       "response_code":"A01",
       "response_desc":"TEST APPROVAL"
    },
    "links":{
      "self":"https://api.forte.net/v3/transactions/trn_63f475e1-d468-4239-b795-cb18fcd1f698",
      "settlements":"https://api.forte.net/v3/transactions/trn_63f475e1-d468-4239-b795-cb18fcd1f698/settlements"
    }
  },
  "source":"ForteCO",
  "type":"transaction.sale",
  "environment":"live"

            

Merchant Application status - Sample Raw Body

Copy
{
    "organization_id": "org_123456",
    "event_id": "evt_6AZrPxX2DUiZCZ3O5Qit3w",
    "MerchantApplication": {
        "application_id": 555555,
        "fee_id": 11111,
        "services_requested": "eCheck - Acquired",
        "decline_reason": [],
        "reject_reason": [],
        "recalledReason": [],
        "status": "approved",
        "received_date": "01/29/2023",
        "received_time": "11:38:12 PM",
        "updated_date": "01/29/2023",
        "updated_time": "11:45:16 PM",
        "organization": {
            "account_id": 123456,
            "dba_name": "test dba",
            "legal_name": "test dba llc"
        }
    },
    "source": "Console",
    "type": "merchantapplication.approved",
    "environment": "live"
}

Additional fields displayed in the response based on the events/status

Events Status Additional Fields in the response based on the status

Approved

approved
  • Type”:"merchantapplication.approved”

Declined declined
  • "decline_reason":["Identity","Type Of Business","Reputation"]

  • "type":"merchantapplication.declined"

Pending pending
  • "type":"merchantapplication.pending"

Received submitted
  • "type":"merchantapplication.received"

Rejected rejected
  • "reject_reason":["Missing or Incomplete Pricing","Incomplete or Invalid Bank Information","Incomplete or Inaccurate TaxID/EIN","Unable to verify SSN","Unable to verify Date of Birth","Invalid Signatures"]

  • "type":"merchantapplication.rejected"

Recalled recalled
  • "recalledReason":["Incomplete Application","Applicant Not Responding","Partner Request"]

  • "type":"merchantapplication.recalled"