# WebHook Control

> Symcon documentation · English · generated on 2026-09-26  
> Index: https://www.symcon.de/en/llms.txt

Source: https://www.symcon.de/en/service/documentation/module-reference/core-instances/webhook-control/

_Requires Symcon >= 4.0_

### Description

The WebHook Control module offers the possibility to call up scripts via a browser. Calls outside the local network are also possible via the Symcon Connect service.
It also offers the option of supplying data to the script.

> **Note:** Scripts executed by the WebHook include these [Systemvariables](../concepts/automations.md)

![Configuration page](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/kern-instanzen/webhook-control/fff8a7af1a-1790424938/webhookcontrol-config.png)

#### Determine the best WebHook

The called hook must not match exactly. The **Best Match**, which is the **longest match**, will always be used. This means that the hook path can be shorter than the hook called, for example, in the browser.

Example Configuration:
* Hook: /hook/ocpp, Target: 12345
* Hook: /hook/ocpp/extra, Target: 55555

Example Calls:
* Call: /hook/ocpp, Best Match: 12345
* Call: /hook/ocpppui, Best Match: 12345
* Call: /hook/ocpp/wallbox1, Best Match: 12345
* Call: /hook/ocpp/extra, Best Match: 55555
* Call: /hook/tester, No Match

#### WebSocket Support
Since Symcon Version 5.2, the WebHook Control uses WebSockets and thus enables real-time transmission.

Received data can be recorded and output as follows:

```php
// When receiving, the data end up in the php://input stream.
IPS_LogMessage("WebSocket", file_get_contents("php://input"));
```

### Integration in Symcon
The WebHook Control is one of the core instances and can therefore be configured immediately.
Within a browser, the respectively linked script can be called with "IP:PORT/hook/HOOKNAME".

To set up a hook, "Add" of the first list must be clicked on in the "WebHook Control" instance. The call name of the hook must first be entered and then the script to be executed by the hook must be selected.

> **Note:** Calls via [Connect Control](connect-control.md) are also possible.

### Example
#### Script call
The sample script to be called is "WebHook TestScript" with ObjectID "35909".

```php
IPS_LogMessage("WebHook GET", print_r($_GET, true));
IPS_LogMessage("WebHook POST", print_r($_POST, true));
IPS_LogMessage("WebHook IPS", print_r($_IPS, true));
IPS_LogMessage("WebHook RAW", file_get_contents("php://input"));
echo "Message: " . $_GET['Message'];
```

The call and the result would be as follows:

![Browser](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/kern-instanzen/webhook-control/6f712f54ad-1790424938/webhookcontrol-browser.png)

The data is passed to the script in arrays at Symcon.

![Message](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/kern-instanzen/webhook-control/8284385988-1790424938/webhookcontrol-meldung.png)

### Authentication
An example of how automatic authentication was implemented via the Control module.
"Symcon" was selected as the user name and "password" was selected as the password.

> **Warning:** Authentication is always recommended to prevent unauthorized access to Symcon from outside.

___Source code___

```php
if(!isset($_SERVER['PHP_AUTH_USER']))
 	$_SERVER['PHP_AUTH_USER'] = "";
if(!isset($_SERVER['PHP_AUTH_PW']))
 	$_SERVER['PHP_AUTH_PW'] = "";

if(($_SERVER['PHP_AUTH_USER'] != "Symcon") || ($_SERVER['PHP_AUTH_PW'] != "passwort")) {
 	header('WWW-Authenticate: Basic Realm="Geofency WebHook"');
 	header('HTTP/1.0 401 Unauthorized');
 	echo "Authorization required";
 	return;
}
echo "Welcome to the protected area";
```

If the hook is called, the query for username and password appears. And the data is sent to the script via $post array.

![Authentification](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/kern-instanzen/webhook-control/b09b6c6bb3-1790424938/webhookcontrol-auth.png)

### Integration via PHP-Module
In addition to the call via script, it is also possible to react to hook calls within a PHP module using the [ProcessHookData](../developer/sdk-tools/sdk-php/module.md) function.

To do this, a hook is registered per [RegisterHook](../developer/sdk-tools/sdk-php/module.md) on the own InstanceID. Subsequently, the "ProcessHookData()" function is automatically called by the Hook Control.

### Example
The example [HookServe](https://github.com/symcon/SymconTest/blob/master/HookServeSimpleStrict/module.php) contains the source code for the complete handling of a WebHook via PHP module with the modern IPSModuleStrict. Usage with the old IPSModule is listed here: [HookServe (Legacy)](https://github.com/symcon/SymconTest/blob/master/HookServeSimple/module.php)

## WC_PushMessage

Source: https://www.symcon.de/en/service/documentation/module-reference/core-instances/webhook-control/wc-pushmessage/

`bool WC_PushMessage(int $InstanceID, string $HookPath, string $Message)`

_Requires Symcon >= 5.2_

sends a WebSocket message to all connected clients

**Parameters**

- `$InstanceID` (int): ID of the WebHook Control
- `$HookPath` (string): Path of the hook
- `$Message` (string): Message to send

**Returns** (bool): If the command succeeds, it returns __TRUE__, otherwise __FALSE__.

Message to send

**Example**

```php
// Sends "Hello World" to the "test" hook of the WebHook Control with ID 12345
WC_PushMessage(12345, "/hook/test", "Hello World");
```

## WC_PushMessageEx

Source: https://www.symcon.de/en/service/documentation/module-reference/core-instances/webhook-control/wc-pushmessageex/

`bool WC_PushMessageEx(int $InstanceID, string $HookPath, string $Text, string $DestinationAddress, int $DestinationPort)`

_Requires Symcon >= 5.3_

sends a WebSocket message to a specific client

**Parameters**

- `$InstanceID` (int): ID des WebHook Control
- `$HookPath` (string): Path of the hook
- `$Text` (string): Message to send
- `$DestinationAddress` (string): IP address to send to
- `$DestinationPort` (int): Port to send to

**Returns** (bool): If the command succeeds, it returns __TRUE__, otherwise __FALSE__.

Port to send to

**Example**

```php
// Sends "Hello World back" to the "test" hook of the WebHook Control with ID 12345. In addition, the client with the address $_SERVER["REMOTE_ADDR"] and port $_SERVER["REMOTE_PORT"] is determined as the recipient.
WC_PushMessageEx(12345, "/hook/test", "Hello world back", $_SERVER["REMOTE_ADDR"], $_SERVER["REMOTE_PORT"]);
```