Webhooks.uno is a REST API that behaves like most modern APIs.
- All API endpoints use JSON to represent data
- Authorization always uses the HTTP
- HTTP status codes work as one would expect: 2xx for success, 4xx for errors in the client side and 5xx for errors in the server side
A few idiosyncrasies:
- Resource data always sits inside a
- Pagination information sits inside the
GETrequests are safe and have no side effects (they never change data
PUTrequests change resources and
PATCHrequests are not supported. There are no plans to support them as they carry additional complexity
POSTrequests create resources
- All resources have an ID and most of them also have an unique name (see more below)
Resource IDs and names
All resources have an unique ID. The format for most resources is
UUIDv4, but not for all of them. The
Message resource, for instance,
does not use UUIDv4. Thus, you should treat the IDs like an opaque string.
Most resources also have names associated to them. Names must be unique for a given resource type within a workspace. For instance, you cannot have two Keys in the same workspace with the same name, but it is possible that your Key name clashes with a Key existing in a different workspace. Most SaaS software have the concept of workspaces, but sometimes is called namespaces or just accounts.
A workspace works just like a tenant by the definition of multi-tenancy.
Authentication / Authorization
All endpoints require authorization. Authorization is done by
passing your authentication token via the
Authorization HTTP header.
Authorization: Bearer YOUR_TOKEN
This is the only method of authorization.
There is no concept of Authentication in webhooks.uno as there is no concept of users. There is only Authorization.
All endpoints that enumerate resources support pagination.
Pagination uses opaque cursors, not page size and page number. Information
regarding pagination comes in the
page attribute of the root object in
the responde body. It may contain three attributes, which are:
has_more, a boolean that tells whether there are more pages. If this is false, there are no more pages left.
size, an integer that tells the size of the page. Note that the page size is fixed and thus NOT configurable.
next, a string which is the cursor to the next page. This is only present if
To get the next page for a request, just pass the cursor in the
attribute in the query parameter
For example, a request to the
/topics endpoint could return something like the following:
To get the results of the next page, you would just call the endpoint passing the next cursor value as a query parameter, like the following request:
In order to return the first page, you may either omit the
parameter, set it to
0 or just set it to an empty value.