Activity Webhooks

Changes to activities and timeframes can be subscribed to using activity webhooks. This allows for example to keep activities and timeframes in sync when they are shared across multiple apps, which otherwise wouldn't know when a change has been submitted by another app.

To set up an activity webhook, you need:

• An activity to which you want to subscribe.
• A callback URL that will be called after any of the subscribed event occurs.
• A secret token that will be passed to the callback URL for authentication.

The following example registers the callback URL https://myapp.example/callback for all events relating to the activity 123 :

// POST /api/v1/activities/123/webhooks/
{
    "webhook_url": "https://myapp.example/callback",
    "secret_token": "56789ABCD",
    "activity_events": true,
    "timeframes_events": true
}

// Response:
{
    "id": 99,
    "webhook_url": "https://myapp.example/callback",
    "secret_token": "56*******",
    "activity_events": true,
    "timeframes_events": true
}

Notice the webhook id returned. This will allow to update or delete the webhook by querying the URL /api/v1/activities/123/webhooks/99/. You can also lists all activity webhooks by using a GET request to /api/v1/activities/123/webhooks/ (response is paginated).

Now let's say the event we are tracking is delayed and we want to update the timeframe 42 associated to this activity:

// PATCH /api/v1/timeframes/42/
{
    "start_time": "2023-03-12T13:00:00+0100"
}

Then this will trigger the sending of the following request:

// POST https://myapp.example/callback
// X-Asi-Api-Token: 56789ABCD
{
  "event": "timeframe-updated",
  "webhook_id": 99,
  "data": {
    "activity_id": 123,
    "timeframe_id": 42
  }
}

Here are all the events that could be triggered for a given activity:

• if setting "activity_events": true, callback will receive following events
  • activity-updated
  • activity-deleted
• if setting "timeframe_events": true, callback will receive following events
  • timeframe-created
  • timeframe-updated
  • timeframe-deleted

The event data sent to the callback URL will only contain the id(s) of the resource(s) (activity or activity+timeframe), so that you will get the actual latest values by issuing an appropriate GET query.