Most organizations never need this, and that is fine. But if you keep a spreadsheet that should update itself, or you use something like Zapier, or your accountant's system wants to know when money arrives, your site can tell it. There are two ways: a webhook, which pushes news out the moment something happens, and an API key, which lets another system read from your site when it wants to. This note covers both. If you have not opened the tool before, How to make edits on an Avistra website shows the sign-in.
Both are for full admins only, and need your passkey. How to set up a passkey on an Avistra website walks through it.
Which one you want
- A webhook is your site telling another system, "this just happened". A member joined; a payment arrived; an order was placed. It goes out within seconds, and you do not have to ask for it.
- An API key is the other way round: another system asking your site for what it already holds, whenever it likes. It can only read, and only what you tick.
If you are following somebody else's setup instructions, they will tell you which one they need. If they ask for an address to send to, that is a webhook. If they ask for a key, it is an API key.
Adding a webhook
Choose the dots at the end of the bar, then Webhooks, or find it under Settings on the Dashboard. Then Add a webhook.
- Address. Where to send it. It must start with
https://, because it carries your organization's news. - Description, so you know what it is for in a year.
- Events. Tick what should be sent. They are grouped: People, Membership, Events, Payments, Donations, Store and Polls. A person added or changed, an application received, a member joined or renewed, a registration made or checked in, a payment received, a refund made, a gift received, an order placed or sent, a poll closed.
- Save webhook.
Each message says who and what changed. Card details are never in one. Fields marked admins-only are left out unless you tick Include admin-only fields, which asks you to confirm, because anybody with access to that system would then see them.
Making sure it works
Open a webhook and there are two things worth using.
- Send a test sends either a plain hello or a made-up example of one of its events, so the other system can be built against something real before anything real happens.
- The delivery log lists what was sent, what came back and when. A message that fails is tried again, backing off over several hours; one that keeps failing stops and says so.
Every change to a webhook is in the audit log: How to give somebody access to your website covers that.
An API key
API keys, from the same screen, makes a key for another system to read with.
- Name it after the system it is for: "Zapier", "the treasurer's spreadsheet".
- Tick what it may read. Nothing else is reachable with it.
- Choose how long it lasts.
- Make the key.
The key itself is shown once, right then. Copy it into the other system straight away; we keep no copy that can be shown to you again, only enough to recognize it. If it is lost, revoke it and make another.
A key can only ever read, never change anything. Every read it makes is in the audit log. It stops working when it expires, when you revoke it, or when the full admin who made it is no longer a full admin.
Ticking people or registrations means whoever holds that key can read names, email addresses and phone numbers until it expires. The tool says so before it makes one. Give a key only to a system you would trust with your list, and give it the shortest life that does the job.
If something is paused
Now and again we pause webhooks while we finish an update. The screen says so, nothing is sent, and changes are off until it is done. Nothing is lost by it.
If you get stuck
Send it to us, or better, send us what the other system is asking for and we will set it up with you. Choose Support request in the bar. How to submit a support request on an Avistra website shows how.