API reference

Webhook endpoint

An address TallyPip sends news to as it happens (the events below). Apps add their own with their key; a business can add them in Settings › Connected apps.

GET /webhooks
POST /webhooks
DELETE /webhooks/{id}

The webhook endpoint object

object string: string; Always "webhook_endpoint".
id id: id; The endpoint's id (a UUID). Use it to fetch it, or to refer to it from other things.
url string: string; The https address messages are sent to.
description string or null: string or null; What it's for.
all_events boolean: boolean; True if it gets every kind of event (now and later ones).
events list: list; The events it gets: customer.created, vendor.created, product.created, invoice.created, invoice.sent, invoice.paid, invoice.voided, payment.received, bill.created, expense.created.
status string: string; active, paused, turned_off (stopped answering for 48 hours) or stopped (its key was revoked).
created_at timestamp: timestamp; When it was added, in UTC.
secret string: string; Only when it's added: the whsec_… secret to check each message's TallyPip-Signature. Keep it.

Example

{
  "object": "webhook_endpoint",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708109",
  "url": "https://hooks.example.com/tallypip",
  "description": "Orders sync",
  "all_events": false,
  "events": [
    "invoice.paid",
    "payment.received"
  ],
  "status": "active",
  "created_at": "2026-10-06T14:30:00.000Z",
  "secret": "whsec_8kZ2…"
}

List webhook endpoints

GET /api/v1/webhooks

The webhook endpoints this key added.

Key: any (Read only works).

Query

limit integer: integer; How many, 1 to 100 (default 25).
starting_after id: id; The last id of the page before, for the next page (when has_more is true).

Newest first. Answers a list: { object: "list", url, has_more, data }.

Request

curl https://tallypip.com/api/v1/webhooks?limit=3 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "list",
  "url": "/api/v1/webhooks",
  "has_more": false,
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708109",
      "url": "https://hooks.example.com/tallypip",
      "description": "Orders sync",
      "all_events": false,
      "events": [
        "invoice.paid",
        "payment.received"
      ],
      "status": "active",
      "created_at": "2026-10-06T14:30:00.000Z",
      "secret": "whsec_8kZ2…"
    }
  ]
}

Try it

With your own key (Settings › Connected apps). It stays in this page only, and reading can't change anything.

Add a webhook endpoint

POST /api/v1/webhooks

Subscribe: send these events to this https address. The answer has its signing secret, once.

Key: any (Read only works).

Body (JSON)

url string: string; Required. An https address on the public internet (not a private or internal one).
events list or "all": list or "all"; Which events, from the list below. Default: all of them.
description string: string; Optional. Shown to the business in Settings › Connected apps.

Answers 201 with the new webhook endpoint. Refused with 400 and the reason (nothing is saved); send an Idempotency-Key so a retry can't make it twice.

Request

curl https://tallypip.com/api/v1/webhooks \
  -H "Authorization: Bearer tpk_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a new id for each change>" \
  -d '{
    "url": "https://hooks.example.com/tallypip",
    "events": [
      "invoice.paid",
      "payment.received"
    ],
    "description": "Orders sync"
  }'

Answer: 201

{
  "object": "webhook_endpoint",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708109",
  "url": "https://hooks.example.com/tallypip",
  "description": "Orders sync",
  "all_events": false,
  "events": [
    "invoice.paid",
    "payment.received"
  ],
  "status": "active",
  "created_at": "2026-10-06T14:30:00.000Z",
  "secret": "whsec_8kZ2…"
}

Remove a webhook endpoint

DELETE /api/v1/webhooks/{id}

Unsubscribe (an endpoint this key added).

Key: any (Read only works).

Only an endpoint added with the same key. Answers { deleted: true }.

Request

curl -X DELETE https://tallypip.com/api/v1/webhooks/3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708109 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "webhook_endpoint",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708109",
  "deleted": true
}