To set up webhooks using the Ordermentum API, follow these organized steps:

Why Use Webhooks?

Webhooks provide a more efficient way to receive updates from the Ordermentum platform compared to polling the API for changes. With webhooks, your application is notified in real-time whenever an event occurs, reducing the need for repeated API calls and improving system performance.

Common use cases include:

• Receiving notifications when a new order is created (order_created).
• Being alerted when an order is updated (order_updated).

Authentication

Before registering webhooks, ensure your application is authenticated with the Ordermentum API. Include your API token in the Authorization header of your webhook registration request.

Refer to the Getting Started Guide for instructions on obtaining an API token.

Registering Webhooks

To register for webhooks, make a POST request to the /v1/webhooks endpoint with the necessary information, including the events you wish to subscribe to and the URL where you want to receive the webhook payloads.

API Endpoint:

POST https://app.ordermentum.com/v1/webhooks
Example cURL Request:

curl -X POST "https://app.ordermentum.com/v1/webhooks" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     --data '{
       "url": "https://your-webhook-url.com/ordermentum-webhook",
       "name": "Ordermentum Order Webhook"
       "events": ["order_created", "order_updated"],
       "entityId": "UUID from your supplier platform",
       "entityType": "supplier"
     }'

Request Body Parameters:

• url: The URL where you want to receive webhook payloads. Ensure this endpoint is publicly accessible and can handle incoming POST requests from the Ordermentum API.
• name: Name of the webhook.
• events: An array of event types you want to subscribe to. Available events are:
  • order_created
  • order_updated
  • purchaser_created
  • purchaser_updated
  • invoice_created
  • invoice_updated
  • credit_note_created
  • credit_note_updated
  • credit_note_completed
  • credit_note_cancelled
• entityId: The unique identifier of your supplier within Ordermentum.
• entityType: The type of entity subscribing to the webhook (e.g., "supplier").

Response:

If the webhook registration is successful, the API will respond with a status code indicating success, including details of the newly registered webhook.

Handling Webhook Payloads

Once registered, the Ordermentum API will send POST requests to your specified URL whenever the subscribed events occur. Your application should be prepared to handle these incoming payloads appropriately.

Example Webhook Payload:

{
  "event": "order_created",
  "timestamp": "2023-07-26T12:34:56Z",
  "data": {
    "id": "17a36ca1-8835-4cf6-a95c-e42bb16d0ca9",
    "createdAt": "2023-07-26T07:59:36.912Z",
    "updatedAt": "2023-07-26T07:59:36.912Z",
    "total": 150.25
  }
}

Handling Tips:

• Respond with a 2xx status code to acknowledge receipt of the webhook.
• Implement retry mechanisms to handle failed deliveries.
• Log incoming webhook events for troubleshooting.
• Our API uses exponential backoff for retries, progressively increasing the delay between attempts, and fails after three unsuccessful attempts.

Authentication Options for Webhooks

When registering a webhook, you can include additional authentication options to secure your endpoint.

Example Configuration:

{
  "authentication": {
    "basicAuth": {
      "username": "your-username",
      "password": "your-password"
    }
  },
  "headers": {
    "Authorization": "Bearer YOUR_CUSTOM_TOKEN"
  }
}

These options allow you to secure your webhook endpoint using basic authentication or custom headers.

Best Practices for Handling Webhooks

1. Secure Your Webhook URL: Always use HTTPS to encrypt data in transit.
2. Verify Payloads: Validate the incoming data to ensure it originates from Ordermentum.
3. Respond Quickly: Ensure your webhook endpoint responds within a reasonable time to avoid retries.
4. Log Events: Keep a log of received events for troubleshooting purposes.