Orderful

The Orderful Developer Hub

Welcome to the Orderful developer hub. Here you'll find everything you need to start working with Orderful as quickly as possible, as well as support resources in case you get stuck. Click GET STARTED to dive in!

Get Started    API Reference

Creating and Receiving a Webhook

Overview

Webhooks are available for newly created transactions that were sent to your organization (when you are the recipient of the transaction).

How To Create a Webhook

Webhooks can be created via the UI by navigating to the Settings tab in the top right of the navigation bar.

Then click on Settings.

From here, you may enter the URL that you would like to receive the transaction_created webhook event for.

After you save the URL, we will provide you with your Secret Key that you can use to verify that we are the sender of the requests.

Secret Key

A Secret Key is a securely generated string that will be used as the shared secret between Orderful and your endpoint. It can be found in the Authorization header of the Webhook request and must be checked before trusting any data within the Webhook request body.

Webhook Behavior

Once you have set your URL in the Webhook settings page you are ready to begin receiving Webhook events. An event will automatically be triggered for any new inbound live Transactions on an active Relationship otherwise the event will need to be manually triggered. To manually trigger an event, navigate to the desired Transaction and click on the "Send to Destination" button on that page:

Receiving a Webhook

A Webhook request will contain the following:

  • Authorization Header
  • X-Correlation-Id Header
  • Event Type and Resource (JSON Body):
{
  "eventType": "TRANSACTION_CREATED",
  "resource": "https://api.orderful.com/v2/transactions/12345"
}

To ingest an incoming Webhook request you must:

  1. Validate the Authorization header of the Webhook request. This value must match what is specified in the Webhooks settings page otherwise you must not trust the data.
  2. Decode the JSON body and check the event type.
  3. Make a GET request using the resource URL and your Orderful API key to retrieve the Transaction.
  4. Once successfully ingested into your system of record make a POST request to the Transaction accept endpoint to update the Transaction status.

Additionally a correlation id is provided to help us troubleshoot any issues that arise with the above process.

Timeouts and Retries

When we send a webhook request, we will wait 30s before retrying the same request if we have not received a response from you.

We will retry up to three times before we give up.

Transaction Statuses and Handling HTTP Status Codes

When we send you a webhook, we will adjust the status of the transaction based on the HTTP response code we receive from you. See below for the expected behavior:

HTTP Response Received
Behavior
Transaction Status

200-series

We do not update the status to an end-state. The transaction must be manually ACCEPTED/REJECTED by the customer via API.

DISPATCHED

400-series

We will update the transaction status immediately and not retry.

REJECTED

500-series

We will retry sending the transaction 3 times before updating the transaction status.

FAILED

You can read more about transaction statuses here.

Updated about a month ago

Creating and Receiving a Webhook


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.