AimRack API

Webhooks

A webhook sends an HTTP POST to an address you choose whenever a record in the table it watches is created, changed or deleted, so your own systems learn of a new customer or a changed order without asking AimRack again and again.

Setting up a webhook

Open and choose New Webhook. Pick the one Table it watches, check which changes send it under Notifications (Insert, Update, Delete; at least one), give it a Name unique in your company, and enter the Webhook URL that receives the POST. A webhook sends while Active is on; switch it off to pause it. To watch several tables, make one webhook for each.

Tables you can watch

Shown in the form as

table

Customer

customer

Quote

quote

Sales Order

salesOrder

Sales RFQ

salesRfq

Sales Invoice

salesInvoice

Item

item

Receipt

receipt

Job

job

Supplier

supplier

Supplier Quote

supplierQuote

Purchase Order

purchaseOrder

Purchase Invoice

purchaseInvoice

Employee

employee

The request body

Each change arrives as one JSON body, sent with Content-Type: application/json:

An order moving out of Draft

{
  "type": "UPDATE",
  "table": "salesOrder",
  "companyId": "<company-id>",
  "eventId": "1042",
  "record": { "id": "<id>", "salesOrderId": "SO000042", "status": "To Ship and Invoice" },
  "old": { "id": "<id>", "salesOrderId": "SO000042", "status": "Draft" }
}

Field

What it holds

type

What happened: INSERT, UPDATE or DELETE.

table

The table the record belongs to, as listed above.

companyId

The company whose record changed.

eventId

This one change. The same on every retry of it, different for every other change, including a second edit to the same record.

record

The record as it is after the change; on a DELETE, as it was just before.

old

The record as it was before the change. Present on UPDATE only, and absent (never null) otherwise.

Delivery and retries

AimRack sends the POST after the change is saved, not while it is saving, so it can arrive a moment after the record changed. Any response status from 200 to 299 counts as delivered. On any other status, or a failed connection, AimRack sends the same change again, up to three more times with longer waits between attempts; after the last it gives up on that change. AimRack sends at most one delivery at a time for any one record.

Each webhook counts its deliveries and failures once per change, not once per attempt, and the webhook list in Settings → Webhooks shows the two as a bar, so a failing address is visible at a glance.

Handling a change delivered twice

Delivery is at least once: a delivery that your address processed but answered too late, or with an error, arrives again. Keep the eventId values you have handled and skip one you have seen. Do not skip on type and record.id: two real edits to the same order share both, and the second would be lost. A change whose retries all fail is not sent again, so when you need every change, compare against the AimRack API from time to time.

Using a webhook with an API key

A webhook tells you that a record changed; an API key lets you fetch the record as it is now, which may have changed again since.