---
title: Webhooks Quick Start
description: Configure a webhook so Somewear pushes data to your server, and see the JSON shape it sends.
url: "https://docs.somewear.app/developer/server-integration/webhooks-quick-start/"
updated: "2026-08-28"
requires:
  features: []
  organizationRole: []
  workspaceRole: []
facets: {}
---

Configure a webhook once, and Somewear pushes data to your server every time it happens — no polling.

> **Note**
>
> [hello-space-server](https://github.com/somewear-labs/hello-space-server) is a minimal sample server that receives Somewear webhooks, if you want a working reference.

## Configure a webhook

> **Warning**
>
> You need a Somewear Organization to create webhooks. To set one up under a team or enterprise plan, contact <sales@somewearlabs.com> or inquire at [somewearlabs.com](https://somewearlabs.com/).

1. Sign in to the [Somewear web app](https://somewear.app).
2. Go to **Account → Settings → Organization Settings**.
3. Click **Add Server Connection → Webhook**.
4. Name your webhook and enter the URL Somewear should POST to. Add basic auth credentials or custom headers (like an API key) if your endpoint needs them.
5. Submit. Somewear tests the webhook with a health-check request.
6. Once saved, click the settings icon to choose which Workspaces push data to this webhook.

## Payload shapes

Every delivery shares one envelope; only the `events[0]` entry changes shape per event type.

`requestId` uniquely identifies this HTTP delivery — use it for idempotency and support lookups. `payloads` is an array (batched deliveries are possible, though today it always carries exactly one item). Each payload’s `identity` names the Workspace Member the event happened to; `account` and `workspace` identify the Organization and Workspace; `device` carries the physical device’s ID and serial.

### Location

`latitude` and `longitude` are decimal degrees as strings, `altitude` is in meters, `timestamp` is ISO 8601 UTC — the same fix a Node or Hotspot reports into the Somewear app, forwarded to your server.

```json
{
  "requestId": "66ef6f9b-8870-4e18-99e1-f14ee7eae91d",
  "payloads": [
    {
      "identity": {
        "id": "0",
        "name": "Example User",
        "type": "User",
        "email": "example@example.com"
      },
      "account": {
        "id": "0",
        "workspaceId": "0"
      },
      "workspace": {
        "id": "0",
        "name": "Example Workspace"
      },
      "device": {
        "id": "0",
        "serial": "SERIAL"
      },
      "events": [
        {
          "type": "Location",
          "latitude": "37.781001",
          "longitude": "-122.393456",
          "altitude": "1000.0",
          "timestamp": "2023-04-12T19:15:14Z"
        }
      ]
    }
  ]
}
```

### Data

An arbitrary base64-encoded byte payload, from a script hook or a hardware integration on the field device.

```json
{
  "requestId": "fe06b693-af2e-49da-963b-97fddaaa97eb",
  "payloads": [
    {
      "identity": {
        "id": "0",
        "name": "Example User",
        "type": "User",
        "email": "example@example.com"
      },
      "account": {
        "id": "0",
        "workspaceId": "0"
      },
      "workspace": {
        "id": "0",
        "name": "Example Workspace"
      },
      "device": {
        "id": "0",
        "serial": "SERIAL"
      },
      "events": [
        {
          "type": "Data",
          "payload": "VGVzdAo=",
          "timestamp": "2023-04-12T18:56:32Z"
        }
      ]
    }
  ]
}
```

### Message

A text message a field user sent.

```json
{
  "requestId": "66ef6f9b-8870-4e18-99e1-f14ee7eae91d",
  "payloads": [
    {
      "identity": {
        "id": "0",
        "name": "Example User",
        "type": "User",
        "email": "example@example.com"
      },
      "account": {
        "id": "0",
        "workspaceId": "0"
      },
      "workspace": {
        "id": "0",
        "name": "Example Workspace"
      },
      "device": {
        "id": "0",
        "serial": "SERIAL"
      },
      "events": [
        {
          "type": "Message",
          "timestamp": "2023-04-12T19:15:14Z",
          "content": "Example content"
        }
      ]
    }
  ]
}
```

### SosEvent

`eventType` is either `Alarm` (the user triggered SOS) or `AlarmCancel` (the user resolved it). `sessionId` groups every event from one SOS session; `latitude`/`longitude` are the position at the moment of the event.

```json
{
  "requestId": "66ef6f9b-8870-4e18-99e1-f14ee7eae91d",
  "payloads": [
    {
      "identity": {
        "id": "0",
        "name": "Example User",
        "type": "User",
        "email": "example@example.com"
      },
      "account": {
        "id": "0",
        "workspaceId": "0"
      },
      "device": {
        "id": "0",
        "serial": "SERIAL"
      },
      "workspace": {
        "id": "0",
        "name": "Example Workspace"
      },
      "events": [
        {
          "type": "SosEvent",
          "eventType": "Alarm",
          "sessionId": "0",
          "latitude": "37.781001",
          "longitude": "-122.393456",
          "timestamp": "2023-04-12T19:15:14Z"
        }
      ]
    }
  ]
}
```