GoFreight provides a webhook system that allows you to subscribe to events that happen in your GoFreight account. 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 account. Once enabled, you will be able to create webhook 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 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 to invoice.created events.

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 an invoice is created in your GoFreight account.

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 includes the x-gofreight-webhook-subscription-ref header, which tells you which subscription the event belongs to so you can look it up.

This header does not authenticate the sender. Any HTTP client can set it, so it is not evidence that GoFreight sent the request. To confirm an event is genuine, verify the HMAC signature before you process it — see Securing Webhooks.