Guide: Configure Webhook via API

This endpoint allows you to configure and automatically verify a device webhook URL directly via the API using your Device Token.

How Automatic Verification Works

Upon receiving the request, the Wagy server will:

1. Validate the URL and enforce SSRF protection (rejecting private IPs, localhost, and internal network ranges).
2. Dispatch a GET challenge request to the target webhook URL:

   GET <webhook_url>?challenge=<random_token>

3. Your webhook server must respond within 5 seconds with HTTP 200 OK and echo the challenge query parameter value in the response body (as plain text or JSON {"challenge": "<random_token>"}).
4. Upon receiving the matching challenge response, Wagy marks webhook_verified as true and generates a fresh webhook_secret (HMAC-SHA256).
5. If verification fails, the request is rejected and the previous webhook configuration is preserved (auto-rollback).

HMAC-SHA256 Security

Store the returned webhook_secret securely. It is used to verify the X-Wagy-Signature header on every incoming webhook event payload sent by Wagy to your server.

---

Set device webhook URL

PUT 
/:device_id/webhook

Automatically configure and verify webhook URL to receive incoming messages (inbound) and message delivery status updates.

Request

Responses

200

Webhook berhasil dikonfigurasi dan diverifikasi

400

URL webhook tidak valid, terdeteksi IP privat/localhost (proteksi SSRF), atau gagal merespons uji verifikasi (challenge response)

401

Tidak terautentikasi (Token perangkat tidak valid)

404

Perangkat tidak ditemukan

500

Terjadi kesalahan internal server