api.tipmoto.com » API documentation » Reference » Webhooks

Webhooks

Hooks are a way for your application to learn about a change on TipMoto.com in real time. The principle is simple: when a change occurs on TipMoto.com, a POST HTTP request is sent (normally within one minute of the change) to the URL you specified. The request contains a description of that specific change, in the same format you get in the agenda change.
Sample output:

<tipmoto>
  <change>
    <id ref="/c/123/change/987654.xml">987654</id>
    <c ref="/c/123.xml">123</c>
    <agenda ref="/c/123/moto.xml">moto</agenda>
    <agendaId ref="/c/123/moto/123456.xml">123456</agendaId>
  </change>
</tipmoto>

Setting up a hook

You can register / update a hook with a request to the agenda:

http(s)://api.tipmoto.com/c/{dealer ID}/hook.{format}

using the following PUT or POST request. Example in XML format:

<tipmoto>
  <hook>
    <url>http://www.vasedomena.cz/vaseaplikace/</url>
    <format>xml</format>
    <method>PUT</method>
    <agenda>moto,dily</agenda>
    <secKey>Verification key (optional)</secKey>
  </hook>
</tipmoto>

It can also be specified in JSON format. An overview of all options is given in the agenda documentation.

Alternatively, you can send a GET request:

http(s)://api.tipmoto.com/c/{dealer ID}/hook.{format}?url=URL&agenda=AGENDA&method=METHOD&secKey=SECKEY

Processing the hook on your side

The hook must be answered with the status code HTTP 200 OK, or a 2xx code, and the hook is then considered processed. The request on your side must return within approx. 15 sec, otherwise the hook may be considered unprocessed. If processing on your side takes longer, we recommend storing the representation of the hook, returning the HTTP code and starting the processing e.g. in another thread.

When an error occurs

If a 2xx code is not returned, we try to deliver the hook repeatedly. First every minute, then delays start to increase (they can be read in the agenda hook in the parameter penalty); after a week the hook is discarded completely.

Keep in mind when processing

Although we try to send hooks in order, by principle we cannot guarantee that they reach your server in the correct order, i.e. if an ad is, for example, updated and then immediately deleted, you may receive the update first and then the deletion. Or, for example, a duplicate may occur and you may receive one hook repeatedly.

Hooks (and changes) carry the methods as they were recorded on Tipmoto. But beware - for example, the EDIT method may also mean that an ad has been removed from or added to the output (see elements forbidden in export)

If you have several dealers

You must register a separate hook for each dealer. One dealer can have several hooks registered via different API logins.

Hooks for the agenda lists

The agenda lists can be watched in the same way.
One hook can be set up per your API access
Although the hook resides in the agenda lists, you must be logged in to access and manage the hook.
You can register / update a hook with a request to the agenda:

http(s)://api.tipmoto.com/lists/listhook.{format}

The format is the same as for the dealer hook, and a GET request can likewise be used. An overview of the watched options is given in the agenda documentation.

Contact us