Developers

Incoming webhooks

Incoming webhooks let an external system create a log by sending a single HTTP request — no API token required. Each webhook posts into one fixed channel.

Overview Sending a request Payload reference Errors

Overview

An incoming webhook is created and configured from within Trailogs — you pick a channel, and optionally set defaults for category, owner, tags, and subjects. Once created, it's issued a unique URL on a dedicated hooks domain, separate from the main API.

Trigger URL format

https://hooks.trailogs.com/webhooks/{token}

The URL itself is the credential — anyone who has it can create logs in the channel the webhook was configured for. Treat it like a secret.

Sending a request

POST/webhooks/{token}

Create a log via webhook

No Authorization header is required — the token in the path identifies the webhook and its target channel. Send a JSON body with Content-Type: application/json. Requests are rate-limited to 60 per minute per source IP.

Example request

curl -X POST https://hooks.trailogs.com/webhooks/{token} \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Payment failed for invoice #4821",
    "content": "Card declined: insufficient funds.",
    "tag_ids": ["tag_uuid"]
  }'

Response · 201

{
  "id": "log_uuid"
}

The response is a minimal object rather than a full log — fetch it from the main API if you need the complete record (requires a bearer token).

Payload reference

The channel is fixed by the webhook's configuration and can't be set in the request body. Any field not listed below is rejected as a validation error.

Field	Type	Required	Description
title	string	Required	Up to 500 characters.
content	string	Optional	Free-form body text.
occurred_at	timestamp	Optional	When the event happened. Defaults to the time the request is received.
category_id	uuid	Optional	Falls back to the webhook's default category if omitted. One of the two must resolve, or the request fails.
owner_member_id	uuid	Optional	Falls back to the webhook's default owner if omitted. One of the two must resolve.
participant_ids	uuid[]	Optional	Other members involved in the event.
tag_ids	uuid[]	Optional	If present, replaces (not merges with) the webhook's default tags.
subject_ids	uuid[]	Optional	If present, replaces the webhook's default subjects. Archived subjects are rejected.

A webhook can be configured with defaults for category, owner, tags, and subjects so that simple integrations only ever need to send title.

Errors

Status	Cause
401	The token doesn't match any webhook.
403	The webhook is disabled, or its workspace is no longer available.
422	Validation failed — a required field is missing, an unrecognized field was sent, no category could be resolved, or a business rule (archived channel/category, workspace log limit) was violated.
429	Rate limit exceeded (60 requests/minute).
503	The webhook's bot member is temporarily unavailable.