Working with the OpenCollective API
OpenCollective is a financial & legal toolkit for grassroots communities. It’s awesome! We’re using it to transparently collect & spend money in the Microsolidarity Network.
Anyone who contributes to our fundraising is welcome to join our monthly members meeting. Until today, whenever a new member joins the Collective, I have had to send them a calendar invitation manually. But today, I learned how to automate that connection (woohoo!).
So here’s a technical blog, about how I used Zapier to automatically invite new OpenCollective members to a recurring Google Calendar event.
You can copy the 4-Step Zap here. I’ll take you through each Step in turn.
Step 1 — Catch the webhook from OpenCollective
On Zapier, I set up the first Step using their Webhooks by Zapier app and the Catch Raw Hook event. This creates a new webhook URL:
Then I went over to the admin panel for our Collective, in the Webhooks section > add new webhook > and there I copied in the URL that Zapier had given me.
To test the connection between OpenCollective (OC) and Zapier, I created a fake account on OC to make a $1 contribution to the Collective.(Alternatively: you could use the OC staging server.)
Then over on Zapier, the “Test Trigger” section showed the data coming through:
Output:
raw_body: {“createdAt”:”2022–10–19T15:29:44.538Z”,”id”:4076674,”type”:”collective.member.created”,”CollectiveId”:528032,”data”:{“member”:{“role”:”BACKER”,”description”:null,”since”:”2022–10–19T15:29:44.523Z”,”memberCollective”:{“id”:502816,”type”:”USER”,”slug”:”richard-bartlett”,”name”:”Richard Bartlett”,…
So far so good!
At this point, Zapier knows that a new member has been created on OC, but we don’t have their email address. Email addresses are not shared over the webhook, otherwise any random stranger could listen on that URL and gather people’s private data.
I’m not a stranger though, I’m the admin for this collective, so I can use the OC API to authenticate myself and prove that I have permission to see their email address.
This takes a couple of steps:
Step 2 — Extract an identifier for the new member
I needed to get a unique identifier for this new member, so I know what to ask the API for.
For the second Step in my Zap, I used their Formatter by Zapier app and the Text event:
I used the “Extract Pattern” transform, which uses a regular expression to pull out a string from the original webhook data.
I took the output from Step 1, searched it with the regex pattern, and it takes that big messy long string of text and strips everything away apart from the slug that I’m looking for:
Pattern:
"slug":"(\S*)",Input:
…”since”:”2022–10–19T15:29:44.523Z”,”memberCollective”:{“id”:502816,”type”:”USER”,”slug”:”richard-bartlett”,”name”:”Richard Bartlett”,…Output:
richard-bartlett
Very good! Now I have a unique identifier which I can use to refer to this new member.
Step 3 — Get the member’s email address from OC
At this point, we need to talk to the OC API. I’ve always found that a daunting task but today I was triumphant! Here’s how I got it to work:
First I had to generate an API Key, which is used by Zapier to impersonate me when it talks to OC. You can generate your own OC API Key here.
Then I read this excellent guide by François Hodierne which showed me how to use GraphQL Playground to interact with the API.
Here’s how it works. I give it:
- the URL for the API: https://api.opencollective.com/graphql/v2/
- my API Key (in the the HTTP Headers)
- the search slug “richard-bartlett” (in the query variables)
… and then it searches for the user account on OC, confirms I have permission to see the email for that account, and returns this result:
Now it is just a matter of converting from GraphQL Playground over to Zapier. Here’s how I got that working.
Using the “copy cURL” function in GraphQL Playground, I generated this API query:
{“query”:”query account($slug: String) {\n account(slug: $slug) {\n id\n name\n slug\n emails\n }\n}\n”,”variables”:{“slug”:”richard-bartlett”}}
For the third Step in my Zap, I used their Webhooks by Zapier app again, this time using a Custom Request event. Here’s how it looks:
Note I had to explicitly set my API Key in the Headers, as well as the Content-type.
Also note: the query was generated for me by GraphQL Playground, but instead of hardcoding the slug as “richard-bartlett”, I replaced that bit with the dynamically generated slug from the previous Step in Zapier.
OK, so at this point, Zapier is notified when a new member is created on Open Collective. It finds the “slug” for the new member, then queries the OC API to find their email address. Now we just need to send them the calendar invite!
Step 4 — Invite new member to calendar event
I set up a new event in Google Calendar, set to recur monthly. (Note: I had issues when I tried to connect Zapier to an old recurring event, so I just made a new one.)
Then I set up the 4th Step in Zapier, using the Google Calendar app and the event Add Attendee/s to Event:
Configuration is super easy: I had to select my Calendar, pick the Event from the list of recent events, and then add the email address from Step 3.
And that’s it! It works!
You can copy the 4-Step Zap here. Happy zapping :)
More about Microsolidarity
Microsolidarity is a community-building practice and a network of community-builders. We’re creating social contexts where people find belonging, mutual support & meaningful work.
Learn more at microsolidarity.cc. If you want to support the Microsolidarity Network, you can make a donation to our Open Collective 🙏
Thanks to Hugi at OC Sweden for guidance in solving this coding puzzle! If you’re an admin for a Collective and you have questions, join the OC Slack and ping me there.