Skip to content

Account Activity API setup script

Jump to bottom
@snowman edited this page Jun 12, 2018 · 8 revisions

Account Activity API script

Script for managing webbook setup and subscriptions.

Introduction  

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.

Premium and enterprise tiers of the Account Activity API

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.

This script helps you:

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.

Getting started  

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 up webhooks  

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.

Triggering CRC check  

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.

Adding subscriptions to a webhook ID  

  • 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.

Updating webhook URL  

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

Error responses  

  • 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."}
Clone this wiki locally