GoFreight provides a webhook system that allows you to subscribe to events that happen in your GoFreight FMS. When one of those events is triggered, we’ll send an HTTP POST payload to the configured callback URL.

Prerequisites

You will need to contact GoFreight staff to enable the webhook system for your GoFreight FMS. Once enabled, you will be able to create webhooks subscriptions with designated events via APIs.

Register a Subscription

In the context of webhooks, a subscription refers to an arrangement established between a webhook provider (the service that generates and sends webhook notifications, which is GoFreight FMS in our case) and a webhook consumer (the recipient or receiver of webhook notifications). This agreement allows you to receive specific types of webhook events from the webhook provider as they occur.

GoFreight provides several APIs allowing our users to manage their webhook subscriptions (checkout GoFreight API doc for details), such as:

  • POST /api/v1/webhook/: Create a new webhook subscription
  • GET /api/v1/webhook/: List all existing webhook subscriptions
  • GET /api/v1/webhook/{ref}/: Get an existing subscription
  • DELETE /api/v1/webhook/{ref}/: Delete an existing subscription

For example, you can use the following cURL command to create a webhook subscription that subscribes only invoice.created events emitted from the FMS.

curl --request POST \
  --url  https://api.core.gofreight.co/api/v1/webhook/ \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-GATEWAY-TOKEN: <your token>' \
  --data '{
    "callback_url": "https://example.com/callback/",
    "event_types": ["invoice.created"],
    "description": "foobar"
}' \
| python -m json.tool

The response body would provide the information about the newly-created webhook subscription:

{
    "data": {
        "ref": "926a3c25-d1e2-4ee6-a303-405a66ede284",
        "callback_url": "https://example.com/callback/",
        "event_types": ["invoice.created"],
        "secret": "Tr5Tkf8wRHsvWiZt",
        "description": "foobar",
        "enabled": true,
        "created_at": "2023-09-08T09:51:42.899365Z",
        "updated_at": "2023-09-08T09:51:42.899336Z"
    }
}

With this subscription, an invoice.created event will be posted to the given callback URL https://example.com/callback/ whenever there is an invoice in the FMS being created.

Retrieve a Subscription

After you’ve created a webhook subscription, you can store the ref from the response body in your system. This ref can then be utilized to retrieve the subscription and verify incoming events.

Additionally, the webhook event request from FMS includes the x-gofreight-webhook-subscription-ref header. This header assists in retrieving the subscription to identify whether the event originates from GoFreight FMS and which specific subscription it pertains to.