Open this in Magpie

A webhook sends each new response to your forms to another app, such as Zapier, Make, n8n or your own server, as it arrives. Team admins add and change a team's webhooks.

Add a webhook

  1. In Forms, choose Webhooks.
  2. Choose Add webhook.
  3. Give it a name, and paste the address the other app gives you, such as a Zapier Catch Hook address.
  4. Choose Add webhook.

The webhook's page opens with its signing secret. Copy the secret then: it will not be shown again.

A new webhook sends the responses of every form in the team. To send one form's responses only, choose that form under Forms on the webhook's page.

A team can have up to 20 webhooks. A form's Form settings shows how many of them send its responses, and links to Webhooks.

When a response is sent

  • A response to a form without payment will be sent as soon as it is saved.
  • A response to a form that takes a payment will be sent once it is paid. A response that is never paid is not sent.
  • Each response will be sent once to each webhook.

What each request holds

Each request is a POST with a JSON body. Its type is form.response.created, and its data has:

  • team: the team's id and name.
  • form: the form's uuid, title, address and version.
  • response: its uuid, when it was sent (submitted_at, in UTC), its address in Magpie, its answers and its payment.

answers lists every question of the form, in order, each with its id, label, type and value. A question that was not answered has the value null. A Checkboxes answer is a list of the choices ticked.

A file is not sent itself. Its value has the file's name and a url that downloads it with an API key. Send the key, and X-Magpie-Team-Id with the team's id (see API keys and REST API).

payment is null on a form without payment. Otherwise it has the state, the amount in the smallest unit of the currency, the currency and when it was paid.

Check that a request came from Magpie

Each request has the headers X-Magpie-Event, X-Magpie-Id, X-Magpie-Timestamp and X-Magpie-Signature.

  1. Join the timestamp, a full stop and the raw body.
  2. Compute their HMAC-SHA256 with the signing secret.
  3. Compare it with the v1 value in X-Magpie-Signature (t=<timestamp>,v1=<signature>).

X-Magpie-Id stays the same when a response is sent again. Keep it, and ignore a request whose id you already have.

Deliveries that fail

Answer with any 2xx status. Any other answer, or no answer, will be tried again after 1, 5 and 30 minutes, then 2, 6, 12 and 24 hours. After 8 attempts the delivery fails.

The webhook's page lists its last 50 deliveries. Send again sends a failed one again, with the same id.

Turning a webhook off, changing its address or its form, or deleting it cancels the responses it has not received yet.

Change or delete a webhook

On the webhook's page:

  • Click its name or its Address to change it.
  • Turn On off to stop sending without deleting the webhook.
  • Choose More, then New signing secret, to replace the secret. The old one stops working, so update the app that receives the webhook.
  • Choose More, then Delete webhook.

Webhooks in the API

A program can add, change and delete webhooks with an API key, at /api/v1/forms/webhooks. The full reference is linked from /docs/api.

If a webhook's signature does not match, or a response is not sent, Contact support.

Ask Magpie support

Send Magpie staff a question about anything this article does not answer.