Webhooks

Webhooks notify your application in real-time when events occur in GSMtasks, via an HTTP POST to the URL you specify.

You can configure webhooks from the Account settings area in the GSMtasks web application or via the Webhooks API.

Event types

Enable one or more event types on each webhook.

Event type	Topic header	Description
Task events	`taskevent.create`	Task state changes and updates (create, assign, complete, etc.)
Documents	`document.create`	Images, videos, or other documents attached to a task
Signatures	`signature.create`	Signature images attached to a task
Reviews	`review.create`	Reviews from trackers

For task events, you can optionally filter which actions trigger the webhook (e.g. only complete and fail). If no filter is set, all task event types are sent.

HTTP delivery

Each webhook delivery is an HTTP POST with a JSON body.

Headers

Header	Description
`Content-Type`	`application/json`
`X-GSMtasks-Topic`	Event topic (e.g. `taskevent.create`, `document.create`)
`X-GSMtasks-Account`	Account UUID
`X-GSMtasks-API-Version`	Webhook API version (e.g. `2.6.0`)
`X-GSMtasks-Hmac-SHA256`	Base64-encoded HMAC-SHA256 signature
`X-GSMtasks-Webhook-Request-Id`	Unique request UUID

Custom headers configured on the webhook are also included.

Verifying signatures

Every webhook has a shared_secret generated on creation. Use it to verify that requests originate from GSMtasks by computing the HMAC-SHA256 of the raw request body and comparing it with the X-GSMtasks-Hmac-SHA256 header.

const crypto = require('crypto')
 
function verifyWebhook(sharedSecret, requestBody, signatureHeader) {
  const hmac = crypto.createHmac('sha256', sharedSecret)
  hmac.update(requestBody)
  const expected = hmac.digest('base64')
  return expected === signatureHeader
}

Retries

Failed deliveries are retried up to 10 times with exponential backoff. The delay between retries follows the formula (attempt + 1)² × 16 seconds.

If all retries are exhausted, the webhook is marked as failed and an email notification is sent to the account owner.

💡

A failed webhook stops sending events until it is manually reactivated from the account settings.

Payload schemas

All payloads include hyperlinked URLs to related resources. The task field is inlined as a full object for task events (API version 2.0.0+) and for document/signature events (API version 2.6.0+).

Task event payload

Sent when a task state change or update occurs.

Field	Type	Description
`id`	UUID	Task event ID
`url`	URL	Task event resource URL
`account`	URL	Account resource URL
`task`	Object	Full task object (inlined)
`task_command`	URL	Related task command URL
`field`	String	Changed field (`state` or `assignee_proximity`)
`event`	String	Event action (see table below)
`from_state`	String	Previous state value
`to_state`	String	New state value
`user`	URL \| null	User who triggered the event
`notes`	String	Optional notes
`location`	GeoJSON \| null	Location where the event occurred
`assignee`	URL \| null	Assigned user URL
`created_at`	DateTime	ISO 8601 timestamp
`updated_at`	DateTime	ISO 8601 timestamp

Task event actions

Action	Description
`create`	Task created
`assign`	Task assigned to a worker
`accept`	Worker accepted the task
`reject`	Worker rejected the assignment
`unassign`	Task unassigned from worker
`transit`	Worker traveling to location
`activate`	Worker began work on the task
`complete`	Task completed
`fail`	Task failed
`cancel`	Task cancelled
`restart`	Failed task restarted

Example

{
  "id": "a3b2c1d4-e5f6-7890-abcd-ef0123456789",
  "url": "https://api.gsmtasks.com/task_events/a3b2c1d4-e5f6-7890-abcd-ef0123456789/",
  "account": "https://api.gsmtasks.com/accounts/a6f60fdf-d87b-4c5d-b5ec-67a90cd16236/",
  "task": {
    "id": "e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05",
    "url": "https://api.gsmtasks.com/tasks/e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05/",
    "account": "https://api.gsmtasks.com/accounts/a6f60fdf-d87b-4c5d-b5ec-67a90cd16236/",
    "external_id": "order-12345",
    "reference": "REF-001",
    "barcodes": [],
    "category": "assignment",
    "contact": {
      "name": "John Smith",
      "company": "ACME Corp",
      "phones": ["+3725551234"],
      "emails": ["john@example.com"],
      "notes": ""
    },
    "orderer_name": "ACME Corp",
    "contact_address": null,
    "contact_address_external_id": null,
    "state": "completed",
    "assignee": "https://api.gsmtasks.com/users/8495e730-e5c2-400c-8ffc-ad830d4fa6a2/",
    "order": "https://api.gsmtasks.com/orders/d4e5f6a7-b8c9-0123-4567-890abcdef012/",
    "route": "https://api.gsmtasks.com/routes/f6a7b8c9-d0e1-2345-6789-0abcdef01234/",
    "description": "Deliver package to customer",
    "calendar_time": null,
    "complete_after": "2024-03-15T08:00:00+02:00",
    "complete_before": "2024-03-15T12:00:00+02:00",
    "scheduled_time": "2024-03-15T09:00:00+02:00",
    "completed_at": "2024-03-15T09:42:00+02:00",
    "cancelled_at": null,
    "auto_assign": false,
    "assignee_proximity": "away",
    "position": 16343544103.78,
    "priority": 0,
    "duration": "00:30:00",
    "size": null,
    "address": {
      "raw_address": "123 Main Street, Tallinn, Estonia",
      "formatted_address": "123 Main Street, Tallinn, Estonia",
      "location": {
        "type": "Point",
        "coordinates": [24.7536, 59.437]
      }
    },
    "forms": {},
    "documents": [],
    "signatures": [],
    "signers": [],
    "metafields": {},
    "trackers": [],
    "recurrence": null,
    "issues": [],
    "counts": {},
    "actions": ["unassign", "cancel"],
    "created_by": "https://api.gsmtasks.com/users/8495e730-e5c2-400c-8ffc-ad830d4fa6a2/",
    "created_at": "2024-03-14T14:00:00+02:00",
    "updated_at": "2024-03-15T09:42:00+02:00"
  },
  "task_command": "https://api.gsmtasks.com/task_commands/856ae165-9595-4f1d-8377-6f4c4db073d1/",
  "field": "state",
  "event": "complete",
  "from_state": "active",
  "to_state": "completed",
  "user": "https://api.gsmtasks.com/users/8495e730-e5c2-400c-8ffc-ad830d4fa6a2/",
  "notes": "",
  "location": {
    "type": "Point",
    "coordinates": [24.7536, 59.437]
  },
  "assignee": "https://api.gsmtasks.com/users/8495e730-e5c2-400c-8ffc-ad830d4fa6a2/",
  "created_at": "2024-03-15T09:42:00+02:00",
  "updated_at": "2024-03-15T09:42:00+02:00"
}

💡

The inlined task object contains the same fields as the Tasks API. Some fields may be absent depending on the webhook’s configured API version.

Document payload

Sent when a document is attached to a task.

Field	Type	Description
`id`	UUID	Document ID
`url`	URL	Document resource URL
`account`	URL	Account resource URL
`external_id`	String \| null	External identifier
`order`	URL \| null	Related order URL
`task`	Object	Full task object (inlined in API version 2.6.0+)
`recurrence`	URL \| null	Related recurrence URL
`contact_address`	URL \| null	Related contact address URL
`file`	URL	File download URL
`file_name`	String	Original file name
`mimetype`	String	File MIME type (e.g. `image/jpeg`)
`thumbnail`	URL	Thumbnail image URL
`description`	String	Document description
`created_by`	URL	User who created the document
`source`	String	Document source
`visible_to_worker`	Boolean	Visible to assigned worker
`visible_to_client`	Boolean	Visible to client
`created_at`	DateTime	ISO 8601 timestamp
`updated_at`	DateTime	ISO 8601 timestamp

Example

{
  "id": "b4c5d6e7-f8a9-0123-4567-890abcdef012",
  "url": "https://api.gsmtasks.com/documents/b4c5d6e7-f8a9-0123-4567-890abcdef012/",
  "account": "https://api.gsmtasks.com/accounts/a6f60fdf-d87b-4c5d-b5ec-67a90cd16236/",
  "external_id": null,
  "order": "https://api.gsmtasks.com/orders/d4e5f6a7-b8c9-0123-4567-890abcdef012/",
  "task": {
    "id": "e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05",
    "url": "https://api.gsmtasks.com/tasks/e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05/",
    "state": "completed",
    "external_id": "order-12345",
    "description": "Deliver package to customer"
  },
  "recurrence": null,
  "contact_address": null,
  "file": "https://files.gsmtasks.com/documents/photo-12345.jpg",
  "file_name": "delivery-proof.jpg",
  "mimetype": "image/jpeg",
  "thumbnail": "https://files.gsmtasks.com/thumbnails/photo-12345.jpg",
  "description": "Proof of delivery",
  "created_by": "https://api.gsmtasks.com/users/8495e730-e5c2-400c-8ffc-ad830d4fa6a2/",
  "source": "mobile",
  "visible_to_worker": true,
  "visible_to_client": false,
  "created_at": "2024-03-15T09:43:00+02:00",
  "updated_at": "2024-03-15T09:43:00+02:00"
}

Signature payload

Sent when a signature is captured on a task.

Field	Type	Description
`id`	UUID	Signature ID
`url`	URL	Signature resource URL
`account`	URL	Account resource URL
`external_id`	String \| null	External identifier
`task`	Object	Full task object (inlined in API version 2.6.0+)
`file`	URL	Signature image URL
`file_name`	String	File name
`mimetype`	String	File MIME type
`thumbnail`	URL	Thumbnail URL
`signer`	Object	Contact who signed (see below)
`documents`	Object[]	Related document objects (full document data)
`location`	GeoJSON \| null	Location where signature was captured
`created_by`	URL	User who captured the signature
`source`	String	Signature source
`created_at`	DateTime	ISO 8601 timestamp
`updated_at`	DateTime	ISO 8601 timestamp

Signer object

Field	Type	Description
`name`	String	Signer name
`company`	String \| null	Company name
`phones`	String[]	Phone numbers
`emails`	String[]	Email addresses
`notes`	String	Notes

Example

{
  "id": "c5d6e7f8-a9b0-1234-5678-90abcdef0123",
  "url": "https://api.gsmtasks.com/signatures/c5d6e7f8-a9b0-1234-5678-90abcdef0123/",
  "account": "https://api.gsmtasks.com/accounts/a6f60fdf-d87b-4c5d-b5ec-67a90cd16236/",
  "external_id": null,
  "task": {
    "id": "e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05",
    "url": "https://api.gsmtasks.com/tasks/e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05/",
    "state": "completed",
    "external_id": "order-12345",
    "description": "Deliver package to customer"
  },
  "file": "https://files.gsmtasks.com/signatures/sig-12345.png",
  "file_name": "signature.png",
  "mimetype": "image/png",
  "thumbnail": "https://files.gsmtasks.com/thumbnails/sig-12345.png",
  "signer": {
    "name": "John Smith",
    "company": "ACME Corp",
    "phones": ["+3725551234"],
    "emails": ["john@example.com"],
    "notes": ""
  },
  "documents": [
    {
      "id": "b4c5d6e7-f8a9-0123-4567-890abcdef012",
      "url": "https://api.gsmtasks.com/documents/b4c5d6e7-f8a9-0123-4567-890abcdef012/",
      "account": "https://api.gsmtasks.com/accounts/a6f60fdf-d87b-4c5d-b5ec-67a90cd16236/",
      "file": "https://files.gsmtasks.com/documents/photo-12345.jpg",
      "file_name": "delivery-proof.jpg",
      "mimetype": "image/jpeg",
      "description": "Proof of delivery"
    }
  ],
  "location": {
    "type": "Point",
    "coordinates": [24.7536, 59.437]
  },
  "created_by": "https://api.gsmtasks.com/users/8495e730-e5c2-400c-8ffc-ad830d4fa6a2/",
  "source": "mobile",
  "created_at": "2024-03-15T09:44:00+02:00",
  "updated_at": "2024-03-15T09:44:00+02:00"
}

Review payload

Sent when a tracker submits a review.

Field	Type	Description
`id`	UUID	Review ID
`account`	URL	Account resource URL
`tracker`	URL	Tracker resource URL
`rating`	Integer	Rating value
`comment`	String \| null	Review comment
`last_task`	URL	Most recent task URL
`last_assignee`	URL	Most recent assignee URL
`created_at`	DateTime	ISO 8601 timestamp

Example

{
  "id": "e7f8a9b0-c1d2-3456-7890-abcdef012345",
  "account": "https://api.gsmtasks.com/accounts/a6f60fdf-d87b-4c5d-b5ec-67a90cd16236/",
  "tracker": "https://api.gsmtasks.com/trackers/f8a9b0c1-d2e3-4567-8901-bcdef0123456/",
  "rating": 5,
  "comment": "Great service, very professional",
  "last_task": "https://api.gsmtasks.com/tasks/e9ba6977-ddc4-41b9-b90b-1ae9b37b3c05/",
  "last_assignee": "https://api.gsmtasks.com/account_roles/a9b0c1d2-e3f4-5678-9012-cdef01234567/",
  "created_at": "2024-03-15T10:00:00+02:00"
}

Orders Uploads