You can use Flock's webhooks to send and receive messages from external services using JSON packets. An incoming webhook posts messages to a Flock channel from an external service.

Create an incoming webhook

• Navigate to the Flock Developer Dashboard at https://dev.flock.com.
• Sign in with your Flock account and click Webhooks on the left.

• Choose to Add an Incoming Webhook.
• Select the Channel where you want incoming messages to be posted.

• Give the webhook a name and an icon that will be used to post messages in Flock.

• Click Save and Generate URL. Copy the URL that is generated.
• This is the webhook endpoint and it accepts JSON packets posted to it. The following command will post a message "This is a test message" to your configured channel:

curl -X POST <Incoming Webhook URL> -H "Content-Type: application/json" -d '{
"text": "This is a test message"
}'

Transforming JSON payload formats

Flock's incoming webhooks support Message objects with two common attributes or keys - "text" for message content and "flockml" for message formatting.

curl -X POST <Incoming Webhook URL> -H "Content-Type: application/json" -d '{
"text": "This is a test message."
}'

OR

curl -X POST <Incoming Webhook URL> -H "Content-Type: application/json" -d '{
"flockml":"<flockml>Hello! Welcome to <b>Flock</b>!</flockml>"
}'

Some external apps and services may send data that does not follow Flock's JSON payload format, and hence it is not parsed.

In the following example, the JSON payload received is not in a compatible format, so no message is generated:

curl -X POST <Incoming Webhook URL> -H "Content-Type: application/json" -d '{
"product": "iPhone", "units": "1", "customer": "Adam", "price": "1000"
}'

To receive messages via an incoming webhook from an app and service that uses an incompatible JSON format, you'll need to transform the data into a Flock-compatible format.

• First, make a note of the keys and values in the JSON payload.
• In the above example, the attributes are "product", "units", "customer", and "price" with the corresponding values being "iPhone", "1", "Adam", and "1000".
• Convert all the incompatible attributes to placeholder keys in the format: $(json.attribute)
• These placeholder keys will be replaced by the corresponding values in the message.
• String together the placeholder keys into an English sentence, and assign it to a key "text" or "flockml".
• Here is an example of the transformation template for the incompatible JSON payload:

{"text": "$(json.customer) bought $(json.units) $(json.product) @ $$$(json.price)"}

• Go to your existing incoming webhook, click Edit and paste the transformation template under Template Heading.

• The webhook will now generate messages in Flock such as "Adam bought 1 iPhone @ $1000".