If another system needs to know when something happens in ThirdSectorBee, such as your website, a volunteer rota or a tool your developer runs, a Worker Bee can send it the event’s details with Call a webhook. The receiving system gets the record as ThirdSectorBee describes it in the event.

Before you start

  • You need workerbees:admin:automations.
  • You also need permission to read the records behind every trigger event you’ve chosen. For example, Contact created needs relationships:read:contacts and Payment created needs relationships:read:fundraisingactivities. If you lack it, Call a webhook isn’t offered. This stops a bee being used to send out data its author couldn’t see.
  • You need the address (URL) of the receiving system, from whoever looks after it. It must be a public web address.

The webhook sends personal data outside ThirdSectorBee. Check that the receiving system is one your organisation trusts and has agreed to use for this data before you create the bee.

Set up the webhook

  1. In the Worker Bee wizard, on the Actions step, choose Worker Bees · Call a webhook.
  2. In URL, enter the receiving address, for example https://example.org/hooks/new-supporter.
  3. Leave Method empty. The request is currently always sent as POST, even if you choose PUT.

  4. If the receiving system needs extra headers, such as an API key, enter them in Headers as JSON:

    { "X-Api-Key": "your-key-here" }

    Each header value must be text. A value that isn’t text is left out, and the flight history records which headers were skipped.

  5. Finish the wizard and choose Create worker bee.

What gets sent

The request body is the event’s details as JSON, with the content type application/json. Fields the bee’s owner isn’t allowed to see are removed first, so the payload matches what you could see yourself.

What you’ll see

Each call appears in the bee’s flight history:

  • Succeeded when the receiving system answers with a success code (200–299).
  • Failed when it answers with any other code, doesn’t answer within 10 seconds, tries to redirect elsewhere, or the URL points to a private or reserved address. Webhook calls aren’t retried, so the receiving system should be ready before you create the bee.

Emit an event instead

Worker Bees · Emit an event publishes a new event inside ThirdSectorBee, which other systems listening to your beehive’s events can act on. It needs an Event type, a name you choose of up to 100 characters, and a Payload in JSON. It has the same permission rule as Call a webhook. Only use it if your developer or administrator has asked for a specific event type; the Worker Bee wizard doesn’t offer custom event types as triggers.