← Back

Throughout This Page

You can jump to the specified sections by clicking on these titles.

• Overview

• Accessing the Webhooks Page

• Creating a Webhook

• Editing a Webhook

• Webhook Website and Connection

Overview

Web applications communicate through API calls, where requests yield responses, and webhooks serve as automatic event triggers that promptly relay information. Unlike API calls requiring periodic data polling, webhooks provide real-time event notifications. This document will guide you on creating and utilizing webhooks within the Shipping API, alongside an overview of the Webhooks page's features.

Accessing the Webhooks Page

To navigate the webhooks page, click the "Webhooks" button in the left-hand menu.

Creating a Webhook

To initiate the webhook creation process, click the "Create Webhook" button in the top-right corner. Subsequently, a pop-up window will appear, prompting you to input the necessary details:

• Name: Provide a unique name for your webhook, which can be anything you prefer.
• Event: Here, you can select the specific events you want to receive notifications from the application. Options include:
  • shipment.created: Notifies you whenever a shipment request (label request) is made.
  • shipment.cancelled: Reports on any canceled shipments in the receiver application.
  • auth.registered: Alerts you each time a new authentication is registered on your Courier API account, which can be managed on the "API Accounts" page.
  • shipment.tracked: Informs you when a shipment is tracked in the receiver application, provided you have enabled tracking in your account settings.
• API Account: Choose the relevant API account to associate with this webhook. API accounts can be configured on the "API Accounts" page.
• Method: Select the HTTP request method for your webhook, typically either PUT or POST. The majority of webhooks use POST to transmit data.
• URL: To set up the webhook, input the URL where the Shipping API should deliver its requests. You can obtain this webhook URL from the destination application to which you wish to send data. If you don't have a specific application, consider using an example like Webhook.site and utilize the provided URL. You can find more information about it in this section.
• Headers: This section is optional but allows you to include additional headers if the target application requires it. Click "Add Header" to add a header and complete the necessary fields.

Once you've filled in these fields, click "Create Webhook." You'll then be prompted to enable the webhook. If you intend to use it, click "Enable Webhook." Following this confirmation, you can view the webhook you've just created.

Editing a Webhook

• Status: This column displays the current status of webhooks, which can be either "Active" or "Inactive." You can toggle the status of each webhook by clicking the corresponding icon to "Enable" or "Disable" it. Please note that if a webhook is inactive, no notifications will be sent by the receiver application.
• Edit: Modify webhook details by clicking the "Edit" button next to it.
• Test: To ensure your webhook is functioning correctly without needing to test API requests and credit consumption, you can test it. Click the related icon, and you'll be presented with the "Request Data" for the specific event (e.g., creating a shipment request) and the subsequent "Response Data" from the receiving application (e.g., Webhook.site). You'll receive a message indicating the success or failure of the test.
• Jobs: Access the "Webhook Jobs" page by clicking the icon associated with each webhook. Here, you'll find information such as:
  • Try Count: Indicates how many attempts have been made to send data to the webhook URL.
  • Date Triggered: Specifies the exact date and time when the webhook event was triggered.
  • Request Log ID: A unique identifier for the request in our system.
  • Last Response Code: Displays the HTTP response code for requests, showing the most recent response code from the Shipping API about that webhook.
  • API Logs: Click the relevant icon in this column to access the "API Request Log" page for more detailed information about the webhook. Additional information on API Request Logs can be found in the dedicated document.
• Logs: This section contains the webhook request logs. Click the associated icon to view the URL, Method, and Response Code details. For a more comprehensive view of the "Request Data" and "Response Data" of the webhook, click "View Request & Response."
• Delete: To remove a webhook, click the bin icon at the end of the row.

Webhook Website and Connection

To acquire your unique URL, visit https://webhook.site/ and use it within the Shipping API. After sending a test notification through the test function, you can verify its presence on the platform, confirming the successful functionality of the webhook you've set up.