Skip to content

19. API keys and webhooks

  • API key: lets your software call EZer to read or write data.
  • Webhook: lets EZer tell your software that something new happened. Your software then pulls the data through the API.
  • An AI assistant: you need no key for that. See the chapter on connecting your AI.

Connect your AI

Both live in ตั้งค่า, on the คีย์ API tab.

Every member can create a key of their own. One key works for one provider, so three providers need three keys. A key never has more rights than its owner. If the owner leaves the provider, the key stops working.

  1. Open ตั้งค่า, the คีย์ API tab, and press สร้าง API key.
  2. Fill the ชื่อ, for example the name of the software that will use this key.
  3. Choose the ระดับสิทธิ์: อ่าน-เขียน or อ่านอย่างเดียว. If the software only reads data, choose read-only.
  4. Choose the อายุการใช้งาน: never, or 1, 7, 30, 90 or 365 days. You choose it only now. You cannot change it later.
  5. Press สร้าง.
  6. EZer shows the key once. Press คัดลอก and store it safely before you press เสร็จแล้ว — ปิด.

The table shows the name, access level, start of the key, owner, last use, expiry and status. A member sees only their own keys. The main administrator and managers see and cancel every key of the provider. If a key leaks, press ยกเลิก key on its row and confirm. A cancelled key cannot be restored, and the row shows ถูกยกเลิก. An expired key also shows ถูกยกเลิก and has no cancel button.

EZer has no rotate button. To replace a key, create a new one, switch your software to it, then cancel the old one.

Send the key in the Authorization header. This example asks what the key can do in one provider. Use your own key, which starts with ezk_, in place of the sample text.

GET /api/providers/{provider_id}/my-access
Authorization: Bearer ezk_xxxxxxxx
  • A request that writes or changes data (POST, PUT, PATCH, DELETE) needs an Idempotency-Key header: a unique string up to 200 characters. If you retry after a network drop, reuse the same value. Without it, EZer answers 400.
  • A read-only key cannot write. Every write answers 403.
  • Errors carry a code. Let your software act on the code. The Thai and English messages are for people.
  • The API does not promise a frozen shape. New fields can appear at any time, so your software must not break on a field it does not know.

The full reference is on the สำหรับนักพัฒนา card in the same tab, with the links เอกสาร API and ข้อกำหนด OpenAPI. Take the server address from that document.

A webhook from EZer is only a nudge. EZer says something new happened, and sends no data or counts with it. Your software must pull the real data through the API with a key. So a repeated or out-of-order nudge does no harm.

The main administrator and managers manage webhooks. The section is hidden from anyone without the right, and you can set it up only while signed in. An API key cannot do it.

  1. In the คีย์ API tab, go to the ปลายทาง Webhook section and press เพิ่มปลายทาง.
  2. Fill the URL where your software takes requests. It must be https and a public internet address. An internal address or your own machine (localhost) is refused. To test, use a service that opens a temporary public https entry.
  3. Tick the events you want under ส่งการแจ้งเตือนเมื่อ. A new endpoint starts with the filing event only.
  4. Press เพิ่ม.

  • รายการถูกล็อกแล้ว: records of a provider for one month were locked. One nudge per event, not per record. It does not mean anything reached the Revenue Department.
  • ลิงก์ชำระเงินออนไลน์เปลี่ยนสถานะ: an online payment link became paid, expired, failed or cancelled. No nudge when it only opens as pending.

Accept online payments

EZer sends a POST with JSON holding type, event_id, provider_id, month (the first day of the month), occurred_at, and subject_id for the payment-link event only. Use event_id to avoid processing twice, then pull the data through the API.

There is no shared secret and no signature to check. EZer proves who it is with a Google ID token in the Authorization header as a Bearer token, whose aud is the URL of your endpoint. The token says who called. It does not prove the body is unaltered, but the body holds no data anyway. Always pull data from the API.

A failure is any answer other than 2xx (a 3xx redirect counts, EZer does not follow it), a connection error, or no answer within 10 seconds. EZer tries six times in all, with gaps of 10 minutes, 30 minutes, 2 hours, 6 hours and 14 hours, about 23 hours in total, then stops. The endpoint’s row shows the ส่งไม่สำเร็จ tag and EZer emails the person who added the endpoint (the main administrator, if that person is gone). EZer never turns an endpoint off by itself. When a later delivery succeeds, the tag clears.

Press the ประวัติการส่ง icon on the row (its name shows on hover) to see each attempt, with its status, event, time, attempt number and error. EZer keeps them for 90 days. The status ยังไม่ได้ส่ง means EZer had no identity to sign the request, so nothing was sent. A row that is not waiting has a ส่งอีกครั้ง button, which uses the same event_id. แก้ไข on the endpoint row changes the URL or the events, and ลบ stops the nudges.

To let an AI assistant work with EZer without writing code, see the chapter on connecting your AI.

Connect your AI