File

---
labels:
- 'Stage-Stable'
summary: Publish to PubSub nodes from via HTTP POST/WebHooks
---

# Introduction

This module is a fairly generic WebHook receiver that lets you easily
publish data to PubSub using a HTTP POST request. The payload can be
Atom feeds, arbitrary XML, or arbitrary JSON. The type should be
indicated via the `Content-Type` header.

-   JSON data is wrapped in a [XEP-0335] container.
-   An Atom feed may have many `<entry>` and each one is published as
    its own PubSub item.
-   Other XML is simply published to the item with ID `current`.

## JSON example

``` {.bash}
curl http://localhost:5280/pubsub_post/princely_musings \
    -H "Content-Type: application/json" \
    --data-binary '{"musing":"To be, or not to be: that is the question"}'
```

## Atom example

``` {.bash}
curl http://localhost:5280/pubsub_post/princely_musings \
    -H "Content-Type: application/xml" \
    --data-binary '<feed xmlns="http://www.w3.org/2005/Atom">
        <entry><title>Hello</title></entry></feed>'
```

## Simple form-data

``` {.bash}
curl http://localhost:5280/pubsub_post/princely_musings \
    --data musing="To be, or not to be: that is the question"
```

# Configuration

All settings are optional.

## Actor identification

First we have to figure out who is making the request.
This is configured on a per-node basis like this:

``` {.lua}
-- Per node secrets
pubsub_post_actors = {
    princely_musings = "hamlet@denmark.lit"
}
pubsub_post_default_actor = "nobody@nowhere.invalid"
```

`pubsub_post_default_actor` is used when trying to publish to a node
that is not listed in `pubsub_post_actors`. Otherwise the IP address
of the connection is used.

## Authentication

[WebSub](https://www.w3.org/TR/2018/REC-websub-20180123/) [Authenticated
Content
Distribution](https://www.w3.org/TR/2018/REC-websub-20180123/#authenticated-content-distribution)
authentication is used.

``` {.lua}
pubsub_post_secrets = {
    princely_musings = "shared secret"
}
pubsub_post_default_secret = "default secret"
```

`pubsub_post_default_secret` is used when trying to publish to a node
that is not listed in `pubsub_post_secrets`. Otherwise the request
proceeds with the previously identified actor.

::: {.alert .alert-danger}
If configured without a secret and a default actor that has permission
to create nodes the service becomes wide open.
:::

## Authorization

Authorization is handled via pubsub affiliations. Publishing requires an
affiliation with the _publish_ capability, usually `"publisher"`.

### Setting up affiliations

Prosodys PubSub module supports [setting affiliations via
XMPP](https://xmpp.org/extensions/xep-0060.html#owner-affiliations),
since 0.11.0, so affiliations can be configured with a capable client.

It can however be done from another plugin:

``` {.lua}
local mod_pubsub = module:depends("pubsub");
local pubsub = mod_pubsub.service;

pubsub:create("princely_musings", true);
pubsub:set_affiliation("princely_musings", true, "127.0.0.1", "publisher");
```

## Data mappings

The datamapper library added in 0.12.0 allows posting JSON and having it
converted to XML based on a special JSON Schema.

``` json
{
   "properties" : {
      "content" : {
         "type" : "string"
      },
      "title" : {
         "type" : "string"
      }
   },
   "type" : "object",
   "xml" : {
      "name" : "musings",
      "namespace" : "urn:example:princely"
   }
}
```

And in the Prosody config file:

``` lua
pubsub_post_mappings = {
    princely_musings = "musings.json";
}
```

Then, POSTing a JSON payload like

``` json
{
   "content" : "To be, or not to be: that is the question",
   "title" : "Soliloquy"
}
```

results in a payload like

``` xml
<musings xmlns="urn:example:princely">
  <title>Soliloquy</title>
  <content>To be, or not to be: that is the question</content>
</musings>
```

being published to the node.