-
Notifications
You must be signed in to change notification settings - Fork 29
Account Activity API setup script
There are several 'plumbing' details that need attention before you can start receiving webhook events in your event consumer application. This script helps automate the fundamental plumbing of the webhook-based Account Activity (AA) API. These are summed up in our "Security Webhooks" and "Managing webhooks and subscriptions" documentations.
Specifically, this script helps with the steps below. See our Account Activity API references (Premium/Enterprise and Enterprise) for the details.
Note: this script was originally written to work with the enterprise endpoints. After the general launch of the premium Account Activity API, it was time to revisit this script and teach it a few 'premium' things...
In terms of the code we'll be reviewing and updating, the main technical difference between premium and enterprise is that the API endpoint/method URLs are different. Premium access is managed with a Twitter developer dashboard, and API URLs contain an :env_name token that is the same as the 'name' you assigned to your AA API instance's environment. On the other hand, enterprise URLs do not include the :env_name token and instead reference a unique, numeric webhook id.
-
Telling Twitter where to send webhook events. This can be a one-time action, but at some point, you will likely need to update the client-side web URL for receiving webhook events. This script manages calls to the API 'set URL' method at these endpoints:
-
Setting up Account Activity API subscriptions. This API is designed to enable receiving events from multiple Twitter accounts. This script manages calls to the API 'add account' method at these endpoints:
-
Managing CRC events from Twitter, and manually triggering those events. In order to start working with the Account Activity API, your event consumer needs to correctly respond to CRC challenges from Twitter. In fact, you will not be able to set up your webhook consumer URL until this step is made. This script manages calls to the API 'test CRC' method at these endpoints:
This script comes along with a clone of the SnowBotDev repository, in the ./scripts directory. There is also a script for managing Direct Message Welcome messages.
If you are a Node.js developer, check out these Node-based scripts for managing webhooks.
The setup_webooks.rb script helps automate Account Activity account details. See HERE.
To run this script you have several options.
$ruby ./scripts/setup_webhooks.rb -h
Usage: setup_webhooks [options]
-c, --config CONFIG Configuration file (including path) that provides account OAuth details.
-t, --task TASK Securing Webhooks Task to perform: trigger CRC ('crc'), set config ('set'), list configs ('list'), delete config ('delete'), subscribe app ('subscribe'), unsubscribe app ('unsubscribe'),get subscription ('subscription').
-u, --url URL Webhooks 'consumer' URL, e.g. https://mydomain.com/webhooks/twitter.
-i, --id ID Webhook ID
-h, --help Display this screen.
- Code requires three gems:
require 'json'
require 'cgi'
require 'optparse'
- Code requires one other SnowBotDev project objects:
This Ruby class manages and abstracts away the OAuth authentication details:
require_relative '../app/helpers/api_oauth_request'
Here are some common uses for this script:
-
Setting client-side URL for webhook events.
- Where should we send the event JSON?
- Looking up what webhook IDs are set up.
- Confirming what webhook 'bridges' have been set up.
- Note: this will trigger a CRC challenge from Twitter, so be sure you are correctly handling that.
Here are some example commands:
-
setup_webhooks.rb -t "list"
Retrieving webhook configurations... No existing configurations... -
setup_webhooks.rb -t "set" -u "https://snowbotdev.herokuapp.com/snowbot"
Setting a webhook configuration... Created webhook instance with webhook_id: 890716673514258432 | pointing to https://snowbotdev.herokuapp.com/snowbot
If your web app is not running, or your CRC code is not quite ready, you will receive the following response:
```
Setting a webhook configuration...
error code: 400 #<Net::HTTPBadRequest:0x007ffe0f710f10>
{"code"=>214, "message"=>"Webhook URL does not meet the requirements. Please consult: https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/guides/securing-webhooks"}
```
-
setup_webhooks.rb -t "list"
Retrieving webhook configurations... Webhook ID 890716673514258432 --> https://snowbotdev.herokuapp.com/snowbot -
setup_webhooks.rb -t "delete" -i 883437804897931264
Attempting to delete configuration for webhook id: 883437804897931264. Webhook configuration for 883437804897931264 was successfully deleted.
Check out our 'Securing webhooks' documentation HERE.
-
setup_webhooks.rb -t "crc"
Retrieving webhook configurations... 204 CRC request successful and webhook status set to valid.
If you receive a response saying the 'Webhook URL does not meet the requirements', make sure your web app is up and running. If you are using a cloud platform, make sure your app is not hibernating.
```
Retrieving webhook configurations...
Too Many Requests - Rate limited...
error: #<Net::HTTPTooManyRequests:0x007fc4239c1190>
{"errors":[{"code":88,"message":"Rate limit exceeded."}]}
Webhook URL does not meet the requirements. Please consult: https://dev.twitter.com/webhook/security
```
If you receive this message you'll need to wait to retry. The default rate limit is one request every 15 minutes.
-
setup_webhooks.rb -t "subscribe" -i webhook_id
Setting subscription for 'host' account for webhook id: 890716673514258432 Webhook subscription for 890716673514258432 was successfully added. -
setup_webhooks.rb -t "unsubscribe" -i webhook_id
Attempting to delete subscription for webhook: 890716673514258432. Webhook subscription for 890716673514258432 was successfully deleted. -
setup_webhooks.rb -t "subscription" -i webhook_id
Retrieving webhook subscriptions... Webhook subscription exists for 890716673514258432.
Sometimes you need to have the Twitter AA API point to a new client-side webhook URL. When building a bot, you may have Twitter initially send webhook events to a development site, then later point to a production system.
When this is the case, you need to first delete the current webhook mapping, then create a new one.
-
setup_webhooks.rb -t "list"
Retrieving webhook configurations... Webhook ID 890716673514258432 --> https://snowbotdev_test.herokuapp.com/snowbot -
setup_webhooks.rb -t "delete" -i 890716673514258432
Attempting to delete configuration for webhook id: 890716673514258432. Webhook configuration for 890716673514258432 was successfully deleted.
Running a 'list' task should confirm there are no longer any webhook ids set up for this Twitter app.
Now, we are ready to update to our production
- setup_webhooks.rb -t "set" -u "https://snowbotdev.herokuapp.com/snowbotdev"
- When you establish and register your webhook URL, you need to include both your app's keys, but also the app owner's Access Tokens. This helps with securing your webhook environment, and may not seem completely intuitive. If you only set the consumer key and secret, you'll likely receive the following message. Include your user access tokens and secret and you should be all set.
Setting a webhook configuration...
POST ERROR occurred with /1.1/account_activity/webhooks.json?url=https%3A%2F%2Fsnowbotdev.herokuapp.com%2Fsnowbotdev, request:
Error code: 403 #<Net::HTTPForbidden:0x007f93fad1f048>
Error Message: {"errors":[{"code":261,"message":"Application cannot perform write actions. Contact Twitter Platform Operations through https://support.twitter.com/forms/platform."}]}
{"code"=>261, "message"=>"Application cannot perform write actions. Contact Twitter Platform Operations through https://support.twitter.com/forms/platform."}
- If you are building a DM integration, like every chatbot, you need to make sure your app has Read, Write and Access direct messages permissions enabled. If you only have Read, Write, you'll trigger an error when attempting to set your webhook URL:
Error code: 401 #<Net::HTTPUnauthorized:0x007fd8880043e0>
Error Message: {"errors":[{"code":32,"message":"Could not authenticate you."}]}
{"code"=>32, "message"=>"Could not authenticate you."}
- Failing CRC check.
Setting a webhook configuration...
POST ERROR occurred with /1.1/account_activity/webhooks.json?url=https%3A%2F%2Fsnowbotdev.herokuapp.com%2Fsnowbotdev, request:
Error code: 400 #<Net::HTTPBadRequest:0x007fe23a197840>
Error Message: {"errors":[{"code":214,"message":"Webhook URL does not meet the requirements. Please consult: https://dev.twitter.com/webhooks/securing"}]}
{"code"=>214, "message"=>"Webhook URL does not meet the requirements. Please consult: https://dev.twitter.com/webhooks/securing"}
Setting a webhook configuration...
POST ERROR occurred with /1.1/account_activity/webhooks.json?url=https%3A%2F%2Fpremiumsnowbot.herokuapp.com%2Fsnowbotdev, request:
Error code: 400 #<Net::HTTPBadRequest:0x007fd7598043e0>
Error Message: {"errors":[{"code":215,"message":"Bad Authentication data."}]}
{"code"=>215, "message"=>"Bad Authentication data."}
- Lack of user permissions, recheck user access token and secret.
Setting subscription for 'host' account for webhook id: 915795063925387264
POST ERROR occurred with /1.1/account_activity/webhooks/915795063925387264/subscriptions.json, request:
Error code: 401 #<Net::HTTPUnauthorized:0x007f971b6c06d8>
Error Message: {"errors":[{"code":348,"message":"Client application is not permitted to access this user's webhook subscriptions."}]}
{"errors":[{"code":348,"message":"Client application is not permitted to access this user's webhook subscriptions."}]}
- Using premium API tier, setting up a webhook URL that is already in use.
Setting a webhook configuration...
POST ERROR occurred with /1.1/account_activity/all/snowing/webhooks.json?url=https%3A%2F%2Fsnowbotdev.herokuapp.com%2Fsnowbotdev, request:
Error code: 409 #<Net::HTTPConflict:0x007fbecfacdce0>
Error Message: {"errors":[{"code":355,"message":"This URL is already in use."}]}
{"code"=>355, "message"=>"This URL is already in use."}