Receive from a URL widget

The Receive from a URL widget gives you a web address of your own. Give that address to another service, such as a form, a payment service, an automation service or a script. Each time the service sends a message to the address, the message arrives in the widget and travels along the wires you draw out of it, into a note, a table or a Send to a URL widget.

The widget itself shows the address, not the messages. To read what arrives, wire it into a note, as described below.

For the opposite direction, sending your desk's updates to another service, use the Send to a URL widget.

Before you start

• The Receive from a URL widget is on every plan.
• You need to be signed in to your PlexiDesk account. The widget creates its address through your account. See Create an account and sign in.
• Messages arrive while PlexiDesk is open, signed in, with the desk that holds the widget open. A message sent at any other time is not kept, so plan for the service to send when you are working, or have it try again.

Add a Receive from a URL widget

1. Open the desk you want it on.
2. Click Add widget in the centre of the header.
3. In the Build & automate column, click Receive from a URL.

You can also right-click an empty part of the desk and choose Add object > Advanced > Receive from a URL, or press ⌘ K on a Mac or Ctrl K on Windows, type receive and choose Add Receive from a URL.

The widget says Creating your URL… for a moment, then shows its address. Each Receive from a URL widget has its own address, and it keeps it.

Copy the address

1. Click Copy beside the address. The button says Copied.
2. Paste the address into the other service, where it asks for a webhook URL or a URL to send to.

Give the address only to the services that should send to this widget: anything sent to it lands on your desk.

What the other service should send

• Method: POST.
• Body: JSON or plain text, up to 256 KB.
• Reply: when the message is accepted, the service gets the reply 202.
• How often: up to 30 messages a minute to one address. Beyond that, messages are refused until the minute is up.

To try it yourself from a terminal, send a short JSON message to the address, for example with curl -X POST -H "content-type: application/json" -d '{"hello":"desk"}' followed by the address.

See what arrives

The widget keeps the last message it received, and passes it along every wire drawn out of it. To read it, wire it into a note:

1. Add a Note, Markdown note or Sticky to the desk.
2. Point at the Receive from a URL widget and click the link button in its title bar. Its tooltip says Click, then click another widget to connect them.
3. Click the note.
4. In How should this connect?, choose Keep in sync.

Each new message now replaces what the note shows. The message arrives exactly as it was sent, so a JSON message appears as JSON.

Where else a message can go

Draw a Keep in sync wire from the widget to any of these:

To pass each message on to another service, wire the widget into a Send to a URL widget. Any kind of wire works for this.

To have AI act on each message, send it into a note first, then wire that note into a Desk agent set to On change. See Send desk updates to other services and receive events back for a worked example.

Wires leaving the widget are listed in the Automations panel, where you can switch each one off. See See what runs on its own on a desk.

Publishing a live view

When you publish a live view of a desk, a Receive from a URL widget shows as a placeholder. Its address is not published. See Publish a live view of a desk.

Common questions

The widget says inbound webhooks aren't available yet. The full message is Inbound webhooks aren't available on your server yet. Once it's updated, reopen this desk and a URL will appear here. It shows when the widget could not create its address, most often because you are not signed in. Sign in, then open another desk and come back to this one.

The service says it sent a message, but nothing arrived. Check that PlexiDesk was open, signed in and showing this desk at the time. Messages sent while it was closed are not kept. Also check that the wire out of the widget is on, in the Automations panel.

Where can I see earlier messages? The widget keeps only the latest one. To keep a running list, wire it into a note and have a Desk agent add each message to a log. See Keep a running summary with a desk agent.

Can I get a new address? Not for the same widget. Add a new Receive from a URL widget for a new address.

Related tasks

• Send desk updates to other services and receive events back
• Send to a URL widget
• Link widgets and set up wires
• See what runs on its own on a desk
• Build & automate widgets