DizLog API
Read your DizLog catalog, stock, customers, sales orders, orders and invoices, and create customers and draft sales orders. Work your CRM: read, create and update leads, log follow-up activities, and read pipeline stages and opportunities. Every request is scoped to the business that owns the API key: send the key in x-api-key. Responses are JSON; amounts and quantities are numbers, timestamps are UTC ISO 8601 and IDs are lower-case UUIDs.
Getting started
The DizLog API lets your own software work with a DizLog business. It can read the business's locations, products, stock, customers, sales orders, orders and invoices, and it can create customers and draft sales orders. Webhooks notify your software when that data changes.
Send every request to https://api-payroll.dizlog.com, or to the sandbox URL if you test in a sandbox (see Authentication). Each API key belongs to one business, and every request reads and writes that business's data.
1. Open API & Webhooks
You must be an owner or admin of the business.
- Sign in to DizLog at https://web.dizlog.com.
- In the sidebar, go to Settings → Integrations → API & Webhooks.
You can also go straight to https://web.dizlog.com/dashboard/business-settings/developers.
2. Create an application
Create one application for each system that connects to DizLog, such as your online shop, ERP or warehouse app. Each application has its own API keys, webhook endpoints, usage history and rate limit.
Select Create application, enter a name, and confirm. You can rename the application later.
3. Create an API key
The Create API key dialog opens as soon as the application is created. To add another key later, open the application and select Create key on the API keys tab.
- Choose Permissions: Read only (the default), Full access, or Custom to pick resources one by one. Give the key only the access it needs. See Authentication for what each permission allows.
- Choose when the key Expires: in 30 days, 90 days (the default), 6 months or 1 year, or on a date you pick. A key can last at most one year.
- Select Create API key and copy the key. It starts with
dz_live_, ordz_test_in sandbox.
This is the only time the full key is shown. DizLog keeps only a fingerprint of it, so a lost key can't be recovered. If you lose it, rotate the key to get a new one.
Every production key works with the business's real data. While you build, use a Read only key. Add write permissions when you are ready to create records.
4. Make your first request
Keep the key in an environment variable, not in your source code. Send it in the x-api-key header:
export DIZLOG_API_KEY="dz_live_…"
curl "https://api-payroll.dizlog.com/v1/products?limit=50" \
-H "x-api-key: $DIZLOG_API_KEY"
The response is one page of products:
{
"data": [
{
"id": "3f6c2a4e-8b1d-4c7a-9e2f-5a1b7c9d0e12",
"name": "Iced Latte 16oz",
"sku": "BEV-LAT-16",
"price": 150,
"currency": "PHP",
"unitOfMeasure": "Per Item",
"updatedAt": "2026-09-18T03:12:45.123Z"
}
],
"limit": 50,
"nextCursor": null
}
Lists come back one page at a time. If nextCursor is not null, send the same request again with the cursor query parameter set to that value to get the next page. API conventions covers paging, errors and rate limits.
5. Get notified of changes (optional)
You don't have to poll the API for changes. Add a webhook endpoint on the application's Webhooks tab. DizLog then sends a signed request to your server whenever sales orders, invoices, customers, products or stock change. See Webhooks.
What you can do
| Resource | Read | Create |
|---|---|---|
| Locations | List and get stores, branches and warehouses | — |
| Products | List and get active products, and list a product's variants | — |
| Inventory | List stock at one location: on hand, reserved and available | — |
| Customers | List and get customers | Create a customer with a name, email, phone and locations |
| Sales orders | List and get sales orders | Create a draft sales order |
| Orders | List and get POS, online-store and marketplace orders, with their lines | — |
| Invoices | List and get invoices, with their status and balance | — |
The API reference lists every endpoint with its parameters, its responses and the permission it needs.
Read orders
Orders are the sales taken at a DizLog POS, the online store or a marketplace. The list covers at most 32 days of createdAt at a time, newest first. This request lists the completed and paid orders of September 2026 in Manila time (+ is sent as %2B):
curl "https://api-payroll.dizlog.com/v1/orders?createdFrom=2026-09-01T00:00:00%2B08:00&createdTo=2026-10-01T00:00:00%2B08:00&status=DONE,PAID" \
-H "x-api-key: $DIZLOG_API_KEY"
Get one order with GET /v1/orders/{id} for its lines. To keep a copy in sync, list with updatedFrom instead; API conventions describes both.
Create a sales order
A sales order created through the API is a draft. It doesn't take payment or move stock. The merchant reviews its pricing and tax and confirms it in DizLog.
You send quantities, not prices. DizLog prices each line from the product's price at the location, or from the product's own price where the location sets none, and applies any matching price list. The line prices can therefore differ from a product's price, which is its catalog base price. That price can be 0 when the merchant sets prices per location.
- Get the
locationIdfromGET /v1/locations. - Get each
productIdfromGET /v1/products. If a product'shasVariantsistrue, get thevariantIdfromGET /v1/products/{id}/variants. - Get the
customerIdfromGET /v1/customers, or create the customer withPOST /v1/customers. - Create the sales order, with a unique
Idempotency-Keyheader for it:
curl -X POST "https://api-payroll.dizlog.com/v1/sales-orders" \
-H "x-api-key: $DIZLOG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: shop-order-10023" \
-d '{
"customerId": "3f6c2a1e-8b4d-4c1a-9e2f-5a7b8c9d0e1f",
"locationId": "8b2fc6e6-1c44-44e1-9b72-1e6db59e77b0",
"currency": "PHP",
"reference": "SHOP-10023",
"items": [
{
"productId": "3f6c2a4e-8b1d-4c7a-9e2f-5a1b7c9d0e12",
"variantId": "9b2e4f10-6a3c-4d8e-b1f7-2c5d8e0a4b36",
"quantity": 2
}
]
}'
Leave out variantId for a product without variants. Send each product and variant once: a repeated line fails with INVALID_REQUEST. If the request times out, send it again with the same Idempotency-Key. DizLog then returns the first sales order instead of creating a second one.
The request fails with PRODUCT_PRICE_NOT_AVAILABLE if an item has no price at that location in that currency, needs a variantId, or is priced by a price list in another currency. The location's price and currency apply, or the product's where the location sets none. The error's details list names each failing item.
Authentication
Send your API key in the x-api-key header of every request:
curl "https://api-payroll.dizlog.com/v1/locations" \
-H "x-api-key: $DIZLOG_API_KEY"
A key is dz_live_ followed by 64 hexadecimal characters, or dz_test_ for a sandbox key. Each key belongs to one application of one business. Owners and admins manage keys in DizLog under Settings → Integrations → API & Webhooks, using their normal DizLog login.
Sandbox
DizLog can set up a sandbox business for you to test with. It runs in a separate DizLog environment with its own base URL, which its API & Webhooks page shows. There:
- keys start with
dz_test_ - each application can make 30 requests per minute
- a sandbox key sent to the production URL, or a production key sent to the sandbox URL, gets
401 UNAUTHORIZED
The key decides the business
Every request works with the data of the business that owns the key. You can't choose another business. A request that sends businessId or business in the query or body, or an x-business-id header, fails with 403 TENANT_OVERRIDE_NOT_ALLOWED.
An ID that belongs to another business behaves as if it doesn't exist. In the path it returns NOT_FOUND. In the query or body it returns LOCATION_NOT_FOUND or CUSTOMER_NOT_FOUND, or PRODUCT_PRICE_NOT_AVAILABLE for a sales order item's productId or variantId. The orders list is the exception: its locationId and customerId filters are filters only, so another business's ID matches no orders and returns an empty page.
Permissions
Each endpoint needs one permission, called a scope. When you create a key, choose Read only, Full access or Custom:
| Scope | Lets the key | Read only | Full access |
|---|---|---|---|
locations:read |
List and get locations | ✓ | ✓ |
products:read |
List and get products and their variants | ✓ | ✓ |
inventory:read |
List stock at a location | ✓ | ✓ |
customers:read |
List and get customers | ✓ | ✓ |
customers:write |
Create customers | ✓ | |
sales_orders:read |
List and get sales orders | ✓ | ✓ |
sales_orders:write |
Create draft sales orders | ✓ | |
orders:read |
List and get POS, online-store and marketplace orders (checkouts). Distinct from sales_orders:read |
✓ | ✓ |
invoices:read |
List and get invoices | ✓ | ✓ |
leads:read |
List and get CRM leads, their activities and the pipeline stages | ✓ | ✓ |
leads:write |
Create and update leads, and log activities on them | ✓ | |
opportunities:read |
List and get sales opportunities (deals) | ✓ | ✓ |
Custom lets you pick scopes one by one. A write scope doesn't include reading, so tick both if your integration also needs to look records up. Give each key only the scopes it needs.
A key without the scope an endpoint needs gets 403 INSUFFICIENT_SCOPE, and the error message names the missing scope. You can't edit a key's scopes. Rotate the key and choose the new scopes.
Manage keys
Open the application's API keys tab. Each application can have up to 10 active keys, and each key shows when it was last used.
- Expiry: every key expires, at most one year after it is created. Rotate it before then.
- Rotate: creates a new key with the scopes and expiry you choose. The old key stops working at once, so have the new key ready to deploy.
- Swap keys with no downtime: create a second key, switch your integration to it, then revoke the first key.
- Revoke: the key stops working at once. You can't undo this.
- Disable the application: on the application's Settings tab. All its keys stop working and its webhook endpoints stop receiving events. Keys and endpoints are kept, and when you enable it again, keys that haven't expired or been revoked work again. Deliveries waiting when you disabled it resume only if they are less than 7 days old, counted from when each was created; older ones are deleted and not sent.
The Activity section of the Settings tab lists the changes made to the application, its keys and its endpoints in the last 90 days.
Keep keys secret
- Keep keys on your server or in a secrets manager.
- Never put a key in browser code, a mobile app, a URL, logs, analytics, source control, screenshots or support tickets.
- If a key might have leaked, revoke it, or rotate it, straight away.
When a request is rejected
| Status and code | Meaning | What to do |
|---|---|---|
401 UNAUTHORIZED |
The key is missing, malformed, unknown, revoked or expired, its application is disabled, or its business is inactive. For security, the response doesn't say which. | Check the key, and check its status on the API keys tab. |
403 TENANT_OVERRIDE_NOT_ALLOWED |
The request tried to choose the business. | Remove businessId, business and x-business-id from the request. |
403 INSUFFICIENT_SCOPE |
The key lacks the scope this endpoint needs. | Rotate the key and add the scope named in the message. |
503 SERVICE_UNAVAILABLE |
The API is temporarily unavailable. | Wait for the number of seconds in Retry-After, then try again. |
DizLog checks the key before it checks anything else about the request. A request with a bad key therefore gets 401 even if its body is also invalid. There are two exceptions, both answered before the key is checked:
- a method and path that match no endpoint get
404 ROUTE_NOT_FOUND - a body that isn't sent as
application/json, isn't valid JSON, is larger than 1 MB, or isn't UTF-8 is rejected
API conventions
These rules apply to every endpoint.
Requests
- The base URL is
https://api-payroll.dizlog.com, and every endpoint starts with/v1. Sandbox has its own base URL; see Authentication. - Send the API key in the
x-api-keyheader. - Send request bodies as UTF-8 JSON with
Content-Type: application/json. A body can be at most 1 MB. Any other content type, such as the form encodingcurl -duses by default, is rejected with415 UNSUPPORTED_MEDIA_TYPE. - Unknown body fields and query parameters are rejected with
INVALID_REQUEST, not ignored. - An optional field sent as
nullor as blank text counts as left out. - IDs are UUIDs. Upper and lower case are both accepted.
- Query filters are combined with AND. A filter that takes several values, such as the orders
status, takes them comma-separated (status=DONE,PAID); repeating the parameter is rejected. - Date-time filters are RFC 3339 with an offset, such as
2026-09-01T00:00:00Zor2026-09-01T00:00:00+08:00. Encode+as%2Bin the query string, or it reads as a space and the value is rejected. - Validation runs in two passes. First every field is checked on its own, and every bad field is reported at once. Only when all fields are valid are the rules between them checked, such as the 32-day window of the orders list.
Responses
A single record comes back as { "data": { … } }. A list comes back as { "data": [ … ], "limit": 50, "nextCursor": "…" }.
-
Fields: every documented field is always present. A missing value is
null, never a missing key. New fields can be added within v1, so ignore fields you don't know. -
IDs: lower-case UUID strings, including IDs you sent, such as the inventory
locationId. -
Amounts and quantities: JSON numbers, rounded to the precision DizLog stores. Prices, sales-order and order amounts have up to 4 decimals, invoice amounts 2, and quantities and stock 6. An invoice's
totalandoutstanding, and an order'stotalandsubtotal, are also rounded by the business's POS rounding rule when it has one, as DizLog shows them; sales orders are not. Parse amounts into a decimal type before doing arithmetic with them. -
Timestamps: ISO 8601 in UTC with a
Zsuffix, such as2026-09-18T03:12:45.123Z. This includes an invoice'sinvoiceDateanddueDate;dueDateisnullwhen the invoice has no due date. -
Text: trimmed. Blank optional text, such as a SKU, address line, email, phone, order number or reference, is
null. A location name can be an empty string. On older records, a customer name can also be an empty string, and a product name can benull. -
Currencies: upper-case ISO 4217 codes, as the merchant set them up.
-
Statuses: a sales order is
DRAFT,CONFIRMED,INVOICEDorCANCELLED. An invoice is currentlyDRAFT,PENDING_APPROVAL,APPROVED,SENT,PAYMENT_PENDING,PARTIALLY_PAID,PAID,CANCELLEDorVOID. More invoice and order statuses can be added, so handle an unknown one without failing. -
Order statuses: an order's
statusis DizLog's own order status. This grouping is for guidance only:Group Statuses Open (still editable, can be deleted) PENDING_OPEN_ORDERAwaiting approval or payment PENDING,PAYMENT_PENDING(charged to a room),PARTIALLY_PAIDIn fulfilment APPROVED,PREPARING,READY_FOR_PICKUP,READY_FOR_DELIVERY,ASSIGNING_DRIVER,ON_ITS_WAY,SCHEDULED,ASSIGNED,IN_TRANSITCompleted DONE(the POS end state),PAID(an online order can bePAIDbefore it is fulfilled),PICKED_UP,DELIVEREDEnded without a sale CANCELLED,VOID,PAYMENT_FAILED,SHIPMENT_REJECTED,SHIPMENT_EXPIREDReturns RETURN_REQUESTED,RETURN_REJECTED,RETURN_ACCEPTED(full and partial refunds)A partial void keeps the status and shows as
quantityReturnedon the lines. -
Order channels:
POS(a DizLog POS, including Web POS and pre-order counters),ONLINE(the online store, guest QR ordering and SellerCraft),INVOICE(created from a DizLog invoice), andGRAB,FOODPANDAandDELIVERECT. More can be added. -
Orders and invoices: every order with
paymentMethodINVOICEalso has an invoice in/v1/invoices. That includes POS sales settled by invoice, whosechannelisPOS. To avoid counting a sale twice, leave orders out onpaymentMethod, not onchannel. -
Order totals: for orders from before 2025 that have no stored total,
totalis computed from the amounts. The order amounts are not guaranteed to add up tototal, because tax already in the prices is part ofsubtotaltoo. Returning or voiding items, including in a refund and exchange, lowerstotalto what remains, and a line'ssubtotalto its remaining quantity ×price;quantityReturnedshows what went back. -
Lines: listing sales orders or orders returns them without their lines. Getting one sales order or order, or creating a sales order, returns it with its items.
-
Stock: quantities can be negative when a merchant sells below zero.
reservedcovers released sales-order fulfilments and approved stock transfers out of the location, andavailableisonHandminusreserved. A bundle'sonHandis derived from its components' stock. Rows withstockTrackedset to false don't track stock at the POS: services (SERVICE, RENTAL_SERVICE, SERVICE_GOODS, with a location's own type taking precedence) and products marked non-inventory for the product or the location. Their quantities are 0 and mean nothing. -
Older records: a few hold a stored amount that isn't a number. Lists leave out such products, sales orders, orders and invoices, and getting one returns
NOT_FOUND. Such a variant price isnull.
Pagination
Lists return one page at a time.
limitsets the page size, from 1 to 100. The default is 50.- To get the next page, send the same request, with the same endpoint and filters, and set
cursorto the previous page'snextCursor. - On the last page,
nextCursorisnull. - Treat a cursor as an opaque value, and don't build or edit one. A cursor that is malformed, or that came from another endpoint or other filters (for orders, the other mode), returns
400 INVALID_CURSOR. Start again from the first page. - Lists are ordered by ID, except orders. A record created while you page shows up on a later page or not at all, and no record repeats.
- Orders are listed newest first by
createdAt, or, withupdatedFrom, oldest change first byupdatedAt. A cursor works only in the mode that returned it: an orders cursor is bound only to its mode, so the other filters andlimitmay change between pages. - Without
updatedFromornumber, the orders list covers a created window of at most 32 days: fromcreatedFromtocreatedTo.createdFromdefaults to 32 days beforecreatedTo, or before now. WhencreatedTois left out,createdFrommay be up to 1 hour older than 32 days, so a walk started at the edge still works on later pages. The default window is relative to each request: for a complete export, send explicitcreatedFromandcreatedTo. - To sync orders, send
updatedFrom. A first sync may start at any time. Start each later sync at the previous sync's start time minus 5 minutes, page untilnextCursoris null, and deduplicate byid: with that overlap no change to an order is missed. A few order fields follow the business's current settings rather than the order, and changing those settings doesn't changeupdatedAt, so a sync won't pick it up:total(rounded with the current POS rounding rule),currency(the business currency) and thenameof a line without a custom name (the product's current name). Get the order again when you need those fields current. Combined with any filter other thannumber,updatedFrommust be within the last 32 days. A deleted open order is not visible, so a sync can't see deletions. - An inventory page can hold fewer rows than
limitand still have anextCursorwhen products change while you page. - Lists don't return a total count.
Rate limits
Each application can make 120 requests per minute, or 30 in sandbox. Every key of the application shares this limit. Each minute is a fixed UTC minute, and the count resets when the next one starts.
Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. Once the limit is used up, requests get 429 RATE_LIMIT_EXCEEDED with a Retry-After header. Wait that many seconds, add a little random delay, and try again.
Idempotency
Creating a customer or a draft sales order requires an Idempotency-Key header. The value is 8–128 ASCII letters, digits, dots, colons, underscores or hyphens. Use a new value for each thing you create, and reuse it when you retry that same request. Your own ID for the record works well, such as shop-order-10023.
- Same key, same body: DizLog returns the record the first request created, with
201, instead of creating another one. It is returned as it is now, not as the first response showed it. - Same key, sent at the same time: the requests wait for the first one to finish and return the same record.
- Same key, different body:
409 IDEMPOTENCY_CONFLICT. Keys are separate for each application and for each kind of record. - After a timeout, a network error, a 5xx or a 429: retry with the same key and the same body. Never retry an uncertain create with a new key, or you may create the record twice.
- After any other 4xx, such as
INVALID_REQUESTorPRODUCT_PRICE_NOT_AVAILABLE: fix the request, then send it with a new key. NOT_FOUNDon a retry: the record the first request created has since been deleted or removed from the business.
Errors
Every error has the same shape:
{
"error": {
"code": "INVALID_REQUEST",
"message": "The request is invalid. See details for each problem.",
"requestId": "5f0c9a8e-2b1d-4c3e-9f7a-6b5c4d3e2f10",
"details": [
{ "field": "items[0].quantity", "message": "must not be less than 0.000001" }
]
}
}
code: branch on this, not onmessageor the HTTP status. Messages are for people and their wording can change. New codes can be added within v1, so handle an unknown code by its HTTP status.details: only onINVALID_REQUESTandPRODUCT_PRICE_NOT_AVAILABLE, with one entry per problem when DizLog can tell which input failed. It can be missing, for example when an item stops being sellable while the sales order is being created.fieldis a path such aslimit,idoritems[0].quantity. Messages never repeat the values you sent.requestId: quote it when you contact support. Never send support your API key or customer data.
| Category | Code | Status | Meaning |
|---|---|---|---|
| Request | INVALID_REQUEST |
400 | A query, path or body value is invalid, or a field or parameter is unknown. See details. |
| Request | MALFORMED_JSON |
400 | The body isn't valid JSON, or its Content-Encoding doesn't decompress. |
| Request | INVALID_CURSOR |
400 | The cursor is malformed, or this endpoint with these filters didn't return it. |
| Request | PAYLOAD_TOO_LARGE |
413 | The body is larger than 1 MB. |
| Request | UNSUPPORTED_MEDIA_TYPE |
415 | The body isn't sent as Content-Type: application/json, or its declared character set isn't UTF-8. |
| Request | ROUTE_NOT_FOUND |
404 | No endpoint matches the method and path. |
| Access | UNAUTHORIZED |
401 | The key is missing, malformed, unknown, revoked or expired, its application is disabled, or its business is inactive. The response doesn't say which. |
| Access | TENANT_OVERRIDE_NOT_ALLOWED |
403 | The request tried to choose the business with businessId, business or x-business-id. |
| Access | INSUFFICIENT_SCOPE |
403 | The key lacks the scope the endpoint needs. The message names it. |
| Idempotency | IDEMPOTENCY_KEY_REQUIRED |
400 | A create request has no Idempotency-Key. |
| Idempotency | IDEMPOTENCY_KEY_INVALID |
400 | The Idempotency-Key isn't 8–128 allowed characters. |
| Idempotency | IDEMPOTENCY_CONFLICT |
409 | The key was already used with a different body. |
| Records | NOT_FOUND |
404 | The record in the path isn't visible to this business. A record that doesn't exist and one of another business look the same. |
| Records | LOCATION_NOT_FOUND |
404 | The locationId in the query or body, or one of a customer's locationIds, isn't a location of this business. The orders list's locationId filter returns an empty page instead. |
| Records | CUSTOMER_NOT_FOUND |
404 | The customerId in the body isn't a customer of this business. |
| Records | STAGE_NOT_FOUND |
404 | The stageId in the body isn't a pipeline stage of this business. The leads list's stageId filter returns an empty page instead. |
| Records | OWNER_NOT_FOUND |
404 | The ownerId in the body isn't an active employee of this business. |
| Records | PRODUCT_PRICE_NOT_AVAILABLE |
400 | One or more sales order items can't be priced at the location in the sales order's currency: no location or product price, a missing variantId for a product with variants, or a price list in another currency. details usually has one entry per failing item. |
| Limits | RATE_LIMIT_EXCEEDED |
429 | The application used up its requests for this minute. Wait Retry-After seconds. |
| Service | SERVICE_UNAVAILABLE |
503 | The API is temporarily unavailable or busy. Wait Retry-After seconds. |
| Service | INTERNAL_ERROR |
500 | An unexpected error. Retry with backoff, and quote requestId if it keeps happening. |
FORBIDDEN (403) and CONFLICT (409) are general codes for a status that has no more specific code. The reference lists the codes each endpoint can return, with an example of each.
A request gets the first error that applies, in this order:
- API key present
- API available
- Key valid
- No business override
- Rate limit
- Scope
- Request validation
Idempotency-Key- Business rules, such as
NOT_FOUNDorPRODUCT_PRICE_NOT_AVAILABLE
Some requests fail before any of these checks: a body that isn't sent as application/json, isn't valid JSON, is too large or isn't UTF-8, and a path that matches no endpoint.
Headers
- Every response has
X-Request-Id. On an error it equalserror.requestId. - Every response has
Cache-Control: no-storeand noETag. Conditional request headers such asIf-None-Matchare ignored, so a request never gets304. X-RateLimit-LimitandX-RateLimit-Remainingappear once the rate limit has been checked. They are missing on401, on a business override, while the API is unavailable, and on body errors that are rejected before any check.429and503responses carryRetry-Afterin seconds.
Data and privacy
- Customer records expose only the customer's ID, name, email, phone and update time.
- Orders expose the customer name entered on the order, which can be a walk-in or table label.
- Reading invoices, orders, customers and CRM leads each needs its own scope.
- CRM leads expose the prospect's contact details, qualification answers and notes, and the name of the employee who owns them. A key sees every lead of its business, whatever the merchant's owner-only lead visibility setting.
- Payroll, salaries, attendance, payment credentials and internal records aren't part of this API.
- DizLog counts requests per application for each UTC day. Owners and admins see these counts on the application's Usage tab.
Versioning
The reference is generated from the API code and checked against it on every change. Changes within v1 only add things: new endpoints, new response fields, new error codes and new invoice statuses. Build your client to accept them. Breaking changes go into a new API version.
Webhooks
Webhooks tell your server when data changes, so it doesn't have to poll the API. When something changes, DizLog sends a signed HTTPS POST to every endpoint that subscribes to that event. The event carries only IDs. Fetch the record from the API to get its current data.
Set up an endpoint
- In Settings → Integrations → API & Webhooks, open the application and go to the Webhooks tab.
- Select Add endpoint.
- Enter the Endpoint URL and pick the Events to receive.
- Select Add endpoint. DizLog sends a
webhook.testevent right away, and the dialog shows how your server answered. - Copy the Signing secret and store it on your server. You need it to check that each request comes from DizLog. You can reveal it again on the endpoint's page. It is not an API key.
Each application can have up to 5 enabled endpoints, and one endpoint can subscribe to any number of events.
The endpoint URL must:
- use HTTPS on the standard port, 443
- use a public hostname, not an IP address,
localhost, or a special-use name such as.test,.example,.invalid,.localor.internal - resolve to public IPv4 addresses. Hosts that have only IPv6 addresses, or that resolve to private, loopback, link-local or reserved addresses, get no deliveries. DizLog checks the address on every delivery.
- not contain a username, password or
#fragment
Events
| Event | Sent when | data |
|---|---|---|
product.created |
A product is created. | id of the product |
product.updated |
A product's name, SKU, price, currency, unit of measure or status changes, or the product is deleted. | id of the product |
inventory.updated |
Stock changes for a product at a location. See the details below. | productId, variantId, locationId |
customer.created |
A customer is added to the business. | id of the customer |
customer.updated |
A customer's name, email or phone changes. | id of the customer |
sales_order.created |
A sales order is created. | id of the sales order |
sales_order.updated |
A sales order is saved, or one of its fulfillments changes. See the details below. | id of the sales order |
invoice.created |
An invoice is created. | id of the invoice |
invoice.paid |
An invoice becomes paid. | id of the invoice |
lead.created |
A CRM lead is created, in DizLog, by a form or import, or through the API. | id of the lead |
lead.updated |
A lead field the API returns changes: status, stage, owner, contact details, qualification answers, notes, tags or conversion. | id of the lead |
lead_activity.created |
A call, email, meeting or task is logged on a lead. | id of the activity, leadId |
lead_activity.updated |
An activity on a lead changes, for example when it is marked done. | id of the activity, leadId |
webhook.test |
You send a test event from the endpoint's page, or add the endpoint. It goes only to that endpoint, and you don't subscribe to it. | { "test": true } |
There are no order events yet. To follow orders, list them with updatedFrom (see API conventions).
Events are created only for endpoints that are enabled, in applications that are enabled. Changes made while an endpoint is disabled are never sent to it.
Details
-
product.updated: other product changes send nothing, including a change toupdatedAtalone. A product'sunitOfMeasureis the current name of its unit, so renaming a unit changes it for every product that uses the unit, but sends nothing and leaves theirupdatedAtunchanged. -
inventory.updated: sent when:- a product is added to a location
- its on-hand stock, status or deletion at a location changes
- its product type or non-inventory setting at a location changes, which decides whether that location tracks its stock
- the stock reserved at a location changes
- a bundle's component stock changes at a location
A fulfillment reserves its lines' stock at its warehouse while it is released, picking, picked or packed. An event is sent when a line is added or removed, or when a line's allocated or shipped quantity changes. One is also sent when a fulfillment enters or leaves those statuses, for example when it ships or is cancelled. Moving between released, picking, picked and packed doesn't change what is reserved, so it sends nothing. Moving a fulfillment that holds stock to another warehouse sends an event for both warehouses.
A stock transfer reserves its lines' stock at the source location while it is pending dispatch or approved. An event is sent when a line's reservation starts, changes or is released, and when the transfer enters or leaves those statuses, for example when it is dispatched or cancelled. Approving a pending transfer doesn't change what is reserved, so it sends nothing.
A bundle's stock comes from its components. When a component's on-hand stock at a location changes, or the component is deleted there, each bundle that uses it at that location gets its own event.
variantIdisnullfor a product without variants. -
customer.created: online-store guest checkouts send nothing. -
lead.updated: saving a lead without changing any field the API returns sends nothing, and so do changes to its attachments, sales channel or usage type. A stage change for a Meta lead sends one event, whatever DizLog also reports to Meta. -
lead_activity.createdandlead_activity.updated: activities logged only on an opportunity send nothing. -
customer.updated: each business the customer belongs to gets its own event. -
sales_order.updated: sent when a sales order is saved, even if only itsupdatedAtchanges. Creating a fulfillment for the sales order also sends it, and so does changing a fulfillment's status or warehouse. Editing only a sales order's items, without changing its totals, sends nothing. -
invoice.paid: sent when an invoice's status becomesPAID, including an invoice created already paid, such as a paid online-store order.- It is sent once each time the invoice becomes paid. If a payment is reversed and made again, you get the event again.
- It doesn't always mean money came in. DizLog counts a credit note applied to the invoice as a payment, so a credit note that settles the invoice, for example after a full return, sends it. So does a partial void that leaves nothing owed on a partly paid invoice.
- A post-dated cheque counts when it is recorded. If it bounces, the invoice reopens without an event.
These changes send no event:
- invoice changes other than becoming paid
- changes to a product variant's SKU or price
- lot and expiry changes to on-hand stock
- changes to a product's own type or non-inventory setting, which apply to every location
- changes to a bundle's components or their quantities
- stock released when a whole fulfillment or order item is deleted
- deleting a customer, sales order, invoice, lead or activity
- changes to pipeline stages and opportunities
What DizLog sends
Each delivery is a POST with a JSON body:
{
"id": "0c2f7d3e-5b1a-4e8f-9d6c-3a2b1c0d9e8f",
"type": "sales_order.updated",
"createdAt": "2026-09-18T03:12:45.123Z",
"data": { "id": "9b2f1c4e-0b45-44e3-9a76-1f2c3d4e5f60" }
}
For inventory.updated, data names the stock row:
{
"productId": "3f6c2a4e-8b1d-4c7a-9e2f-5a1b7c9d0e12",
"variantId": null,
"locationId": "8b2fc6e6-1c44-44e1-9b72-1e6db59e77b0"
}
The request has these headers:
| Header | Value |
|---|---|
Content-Type |
application/json |
User-Agent |
DizLog-Webhooks/1.0 |
DizLog-Event-Id |
The event's id |
DizLog-Signature |
t=<Unix timestamp>,v1=<HMAC-SHA256 hex digest> |
Verify the signature
Check the signature before you trust or process a request:
- Read
tandv1from theDizLog-Signatureheader. - Compute HMAC-SHA256 over
t, a dot, and the raw request body, exactly as received. Use the signing secret text as the key, as it is: don't decode it from hex. - Compare the result with
v1using a constant-time comparison. - Reject the request if
tis more than five minutes away from your server's clock.
In Node.js:
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyWebhook(secret, header, rawBody) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header || '');
if (!match || Math.abs(Date.now() / 1000 - Number(match[1])) > 300) return false;
const expected = createHmac('sha256', secret)
.update(match[1] + '.').update(rawBody).digest();
return timingSafeEqual(expected, Buffer.from(match[2], 'hex'));
}
With Express, read the raw body for the webhook route, so it hasn't been parsed and re-serialized:
import express from 'express';
const app = express();
app.post('/webhooks/dizlog', express.raw({ type: 'application/json' }), (req, res) => {
const secret = process.env.DIZLOG_WEBHOOK_SECRET;
if (!verifyWebhook(secret, req.get('DizLog-Signature'), req.body))
return res.sendStatus(400);
const event = JSON.parse(req.body.toString('utf8'));
// Save the event, answer, then process it in the background.
res.sendStatus(200);
});
Answer within 8 seconds
Answer with any 2xx status within 8 seconds. Save the event first, answer, and then do the work in the background. Everything else counts as a failed attempt:
- a
3xx,4xxor5xxstatus (DizLog doesn't follow redirects) - no answer within 8 seconds
- a refused connection
- a response body larger than 64 KB
Retries
DizLog sends an event shortly after the change is saved, usually within 15 seconds. If the attempt fails, it tries again after 30 seconds, and then after 1, 2, 4 and 8 minutes. That makes 6 attempts over about 15 minutes. After the last failed attempt, the delivery is marked Failed.
Every attempt carries the same event ID and body, with a new signature timestamp.
Duplicates and order
Delivery is at least once, and events can arrive out of order.
- Deduplicate by the event ID, from
DizLog-Event-Idor the body'sid. The same event can arrive again after a retry or a replay, or when your server saved it but its answer didn't reach DizLog. - Don't rely on the order of events. When an event arrives, fetch the record from the API and use its current state.
Monitor deliveries
The endpoint's page lists its deliveries from the last 7 days, newest first. You can filter them by status and by event. Open a delivery to see its payload, its attempts and your server's last answer.
- Send test event sends a
webhook.testevent, at most once a minute. - Replay sends a failed delivery again with the same event ID and a new round of attempts. It works while the endpoint and application are enabled, until 20 minutes before the delivery is 7 days old, so every attempt has time to run.
- Retry now skips the wait before a waiting delivery's next attempt. It has the same 7-day limit as a replay.
A replay or retry goes out within 15 seconds.
Deliveries are deleted after 7 days.
Manage endpoints
- Edit changes the URL or the events. The signing secret stays the same.
- Disable endpoint stops deliveries right away. Deliveries already waiting are paused. When you enable the endpoint again, each one resumes only if it is less than 7 days old; the 7 days count from when the delivery was created, not from when you disabled the endpoint. Disabling the application pauses all of its endpoints in the same way.
- Reveal shows the current signing secret.
- Roll signing secret replaces the secret. DizLog signs with the new secret straight away, and your server rejects requests until it has the new one. Rejected deliveries keep retrying for about 15 minutes. After that, replay any that failed.