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

Note

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.

1. Sign in to the Somewear web 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.

{
  "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.

{
  "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.

{
  "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.

{
  "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"
        }
      ]
    }
  ]
}