Edit

SETHOOK

Syntax

SETHOOK name endpoint [META name value ...] [EX seconds] NEARBY|WITHIN|INTERSECTS key FENCE [DETECT what] [COMMANDS which] param [param...]

Description

Creates a webhook which points to a geofenced search. If a hook is already associated to that name, it'll be overwritten.

Examples

Set a simple hook.

SETHOOK warehouse http://10.0.20.78/endpoint NEARBY fleet FENCE POINT 33.5123 -112.2693 500

In this example we created a webhook named warehouse that watches for changes to objects in the fleet collection. When a change occurs the endpoint 'http://10.0.20.78/endpoint' is notified with a detailed message. The message contains a member named 'detect' which has one of the following values:

  • inside is when an object is inside the specified area.
  • outside is when an object is outside the specified area.
  • enter is when an object that was not previously in the fence has entered the area.
  • exit is when an object that was previously in the fence has exited the area.
  • cross is when an object that was not previously in the fence has entered and exited the area.

For more information on the format of this message please see the topic on Geofencing.

NEARBY, INTERSECTS, and WITHIN are supported search types. The FENCE keyword must be present.

Endpoints

Tile38 currently supports endpoints with the following services:

HTTP / HTTPS

When using the http:// and https:// url scheme an HTTP POST will be sent to the specified url with the content-type of application/json and the request body containing the message.

Tile38 expects that the endpoint will respond with the status code of 200. As long as the status is 200 the message will be considered sent.

GRPC

The grpc:// url scheme provides support for sending messages over GRPC.

For example:

SETHOOK warehouse grpc://10.0.20.78:6798/ ...

All webhook messages will be sent to the GPRC server at 10.0.20.78:6798.

The proto file can be found in the /hservice directory.

Redis

The redis:// url scheme provides support for sending messages to a Redis server.

For example:

SETHOOK warehouse redis://10.0.20.78:6379/warehouse ...

All webhook messages will be sent to the Redis server at 10.0.20.78:6379 in a PUBSUB queue warehouse as a JSON messages.

Disque

The disque:// url scheme provides support for sending messages to a Disque server.

For example:

SETHOOK warehouse disque://10.0.20.78:7711/warehouse?replicate=2 ...

All webhook messages will be sent to the Disque server at 10.0.20.78:7711. The replicate param is optional and when this value is greater than one, Tile38 will require that the Disque server to make copies of the message on N servers, where N is the value of replicate. Please review the Disque API for information on the replicate option.

Kafka

The kafka:// url scheme provides support for sending messages to a Kafka broker.

For example:

SETHOOK warehouse kafka://10.0.20.78:9092/warehouse ...

All webhook messages will be sent to the Kafka server at 10.0.20.78:9092 to a topic called warehouse. The port number is optional and will default to 9092.

Options

  • auth - sasl, tls
  • ssl - true
  • sha256 - true
  • sha512 - true
  • cacert - path/to/ca.crt
  • cert - path/to/user.crt
  • key - path/to/user.key

Authentication

Tile38 currently supports SASL/PLAIN, SASL/SSL and TLS authentication with your Apache Kafka broker.

SASL PLAIN

Add KAFKA_USERNAME and KAFKA_PASSWORD to your environment. Then you can set the hook as follows:

SETHOOK warehouse kafka://10.0.20.78:9092/warehouse?auth=sasl&ssl=false&sha512=true ...
SASL / SSL

Add KAFKA_USERNAME and KAFKA_PASSWORD to your environment. Make sure to mount the root certificate of your broker into your Tile38 leader. Then you can set the hook as follows:

SETHOOK warehouse kafka://10.0.20.78:9092/warehouse?auth=sasl&ssl=true&sha512=true&cacert=path/to/ca.crt ...

where sha256 or sha512 depend on the authentication that has been setup in your broker.

TLS

Make sure that the root certificate of your broker as well as the user certificate and the key are mounted into the Tile38 leader instance. Then setup as follows:

SETHOOK warehouse kafka://10.0.20.78:9092/warehouse?auth=tls&cacert=path/to/ca.crt&cert=/path/to/user.crt&key=/path/to/user.key ...

AMQP

The amqp:// url scheme provides support for sending messages to a RabbitMQ broker via the Advanced Message Queuing Protocol (AMQP) version 0.9.1.

For example:

SETHOOK warehouse amqp://guest:guest@10.0.20.78:5672/warehouse?route=tile ...

All webhook messages will be sent to the RabbitMQ broker at 10.0.20.78:5672 to the queue called warehouse. Route is an optional parameter and will default to tile38.

Options

The following optional parameters are available for this hook, the listed value is the default value:

  • type - 'direct'
  • durable - true
  • immediate - false
  • mandatory - false
  • auto_delete - false
  • internal - false
  • no_wait - false
  • delivery_mode - 1
  • route - tile38

MQTT

The mqtt:// url scheme provides support for sending messages to a MQTT broker

For example:

SETHOOK warehouse mqtt://10.0.1.1:8443/mytopic?qos=1&retained=0 ...

All webhook messages will be sent to the MQTT broker at 10.0.1.1:8443 to the topic called mytopic.

Options

The following optional parameters are available for this hook, the listed value is the default value:

  • qos - 0
  • retained - false
  • cacert - empty string
  • cert - empty string
  • key - empty string

SQS

Sending to SQS requires the URL endpoint that AWS provides.

For example:

SETHOOK warehouse https://sqs.us-east-1.amazonaws.com/349840735605/myqueue ...

All webhook messages will be sent to the SQS queue named myqueue in the region us-east-1 with the queue id 349840735605.

SQS credentials will be automatically chosen from one of the following:

  • ~/.aws/credentials
  • Environment variables
  • EC2 Role

Options

The following optional parameters are available for this hook, the listed value is the default value:

  • credpath - empty string
  • credprofile - empty string
  • createqueue - false

The createqueue param will attempt to create the queue if does not exist.

NATS

The nats:// url scheme provides support for sending messages to a NATS topic

For example:

SETHOOK warehouse nats://127.0.0.1:42222/mytopic?user=admin?pass=123 ...

All webhook messages will be sent to the NATS server at 127.0.0.1:4222 to the topic named mytopic and the username admin and password 123

Options

The following optional parameters are available for this hook, the listed value is the default value:

  • user - empty string
  • pass - empty string

Azure Event Hub

Messages can be sent to an Azure Event Hub by specifying the Event Hub connection string.

For example:

SETHOOK warehouse Endpoint=sb://event-hub-namespace.windows.net/;SharedAccessKeyName=sharedAccessKeyName;SharedAccessKey=***Secret***;EntityPath=event-hub-name ...

All webhook messages will be sent to the Event Hub in namespace event-hub-namespace to the Event Hub event-hub-name.

The connection string can be found from the Azure Portal blade for the Event Hub in question. Validation will fail if any of the connection string elements (Endpoint, SharedAccessKeyName, SharedAccessKey or EntityPath) are missing or not in the order shown in the example.

Google Pubsub

Messages can be sent to a Google Pubsub endpoint.

For example:

SETHOOK warehouse pubsub://my-gcp-project:my-topic?credpath=/path/to/creds/key.json NEARBY fleet FENCE POINT 33.5123 -112.2693 500

Endpoint Failover

It's possible to specify multiple endpoints for a webhook by separating each with a comma. Make sure that there are no spaces between the comma and the urls.

SETHOOK warehouse http://10.0.20.78/ep1,http://10.0.20.78/ep2 ...

Tile38 will try to send a message to the first endpoint. If the send is a failure then the second endpoint is tried, and so on.

Related Commands

DELHOOK
HOOKS
PDELHOOK
SETHOOK