# Webhooks

Part of the [GeoDynamics API](/api/geodynamics/index.md). Host: `https://api.geodynamics.dev`.

Webhooks allow you to build or set up integrations, which subscribe to certain events in GeoDynamics. When one of those events is triggered, we'll send an HTTPS POST payload to the webhook's configured URL. Webhooks can be used to trigger your ERP, dispatch solution.. and so many other things. You're only limited by your imagination.

Webhooks can be enabled per company. Once active, the webhook will be triggered each time one or more subscribed events occur.

## Events

| Event | Event Type | Description |
| :-- | --- | --- |
| Add clocking | `webhook.addclocking` | Triggered when a clocking is added. |
| Update clocking | `webhook.clocking.update` | Triggered when a clocking is updated. |
| Delete clocking | `webhook.clocking.delete` | Triggered when a clocking is deleted. |
| Add asset | `webhook.asset.add` | Triggered when an asset is added. |
| Update asset | `webhook.asset.update` | Triggered when an asset is updated. |
| Delete asset | `webhook.asset.delete` | Triggered when an asset is deleted. |
| Asset movement | `webhook.assetmovement.add` | Triggered when an asset has moved. |
| AccessLog | `webhook.accesslog` | Triggered when someone has badged for access control. |

## Payloads

Each event type has a specific payload format with the relevant event information.

## Endpoints

The customer can configure his own endpoints. All payloads are deliverd to all endpoints.

## Delivery headers

HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers.

| Header | Description |
| :-- | --- |
| `sharedsecretkey` | A shared secret to verify GeoDynamics as the sender. Example value: `a46a6975-8524-4304-1547-1b57018f11d5` |
| `timestamp` | Moment of delivery of the message in Unix time. Example value: `1545294527` |
| `event-type` | The event type, as described in Events. Example value: `webhook.addclocking` |

## Limitations and rate limits

Webhooks are limited to no more than one request per second, we will group the messages in one request where possible.

A webhook is defined as sent when we get a `2xx`, `3xx` or `410` response. If we get a `4xx`, `5xx` or no respone after 5 seconds it is marked as not sent. An event that was not sent will be retried 47 times, before each retry we wait an hour.

## Clocking sources

'New clocking' deliveries will contain a clocking source. This is an overview of possible clocking sources and their meaning.

| Clocking source | Name | Description |
| :-- | --- | --- |
| 0 | Automatic | Received from a vehicle's blackbox or a timeclock. |
| 1 | Manual | Manually created via our website. |
| 2 | IVR | Received via our phone API. |
| 3 | Mobile device | Created via our Time App (iOS/Android). |
| 4 | Mobile RFID scanner | Created via mobile RFID (JWM). |

## POST your endpoint URL

Webhook: we POST to a URL you host. There is no path on this API host to call.

Access log

### Header parameters

| Name | Type | Required | Example |
| --- | --- | --- | --- |
| `sharedsecretkey` e.g. a04a6229-9300-4304-9163-1b57018f11d5 | string | optional | `a04a6229-9300-4304-9163-1b57018f11d5` |
| `timestamp` e.g. 1545294527 | string | optional | `1545294527` |
| `event-type` e.g. webhook.assetmovement.add | string | optional | `webhook.assetmovement.add` |

### Request body

Type: `object`

| Field | Type | Required |
| --- | --- | --- |
| `DateTime` | string | optional |
| `UserId` | string | optional |
| `UserName` | string | optional |
| `LocationId` | string | optional |
| `LocationName` | string | optional |
| `RelaisId` | string | optional |
| `RelaisName` | string | optional |
| `ReaderId` | string | optional |
| `ReaderName` | string | optional |
| `Badge` | string | optional |
| `AccessGranted` | boolean | optional |
| `Reason` | string | optional |