Webhooks#

Webhooks service forwards received platform messages to external HTTP endpoints. When a message is published to a profile with webhooks enabled, the service delivers that message as an HTTP POST to each webhook URL registered for the thing's group.

Webhooks are group-scoped records that define a target URL, optional HTTP headers, and a name. Multiple webhooks can be registered per group, and all of them receive a copy of each matching message.

Enabling webhooks#

Webhooks are enabled by setting the webhook field to true in the Profile Config. When a message is received for that profile, the service will forward it to all webhooks registered for the thing's group.

{
  "config": {
    "content_type": "application/json",
    "write": true,
    "webhook": true,
    "smtp_id": ""
  }
}

If write is set to false, the message is forwarded to webhooks but not stored in the database.

Managing webhooks#

Webhooks are group-scoped. To register a webhook, you supply a name, target URL, and an optional map of HTTP headers to include in the forwarded request. Headers can carry authentication credentials for the receiving system.

# Create webhooks for a group
curl -s -S -i -X POST \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '[{
    "name": "Data pipeline",
    "url": "https://ingest.example.com/mainflux",
    "headers": {"X-Api-Key": "<api_key>"}
  }]' \
  https://localhost/webhooks/things/<thing_id>/webhooks

[
  {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "Data pipeline",
    "url": "https://ingest.example.com/mainflux",
    "headers": {"X-Api-Key": "<api_key>"},
    "group_id": "211e4567-e89b-12d3-a456-426614174000"
  }
]

# List webhooks for a thing
curl -s -S -i \
  -H "Authorization: Bearer <user_token>" \
  https://localhost/webhooks/things/<thing_id>/webhooks

# List webhooks for a group
curl -s -S -i \
  -H "Authorization: Bearer <user_token>" \
  https://localhost/webhooks/groups/<group_id>/webhooks

# View a specific webhook
curl -s -S -i \
  -H "Authorization: Bearer <user_token>" \
  https://localhost/webhooks/webhooks/<webhook_id>

# Update a webhook
curl -s -S -i -X PUT \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data pipeline",
    "url": "https://ingest.example.com/mainflux-v2",
    "headers": {"X-Api-Key": "<api_key>"}
  }' \
  https://localhost/webhooks/webhooks/<webhook_id>

# Remove webhooks
curl -s -S -i -X DELETE \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{"webhook_ids": ["<webhook_id>"]}' \
  https://localhost/webhooks/webhooks

For the full API reference, see the API documentation.