ICS calendar feeds#

IncidentRelay can generate tokenized ICS subscription feeds for team on-call schedules. This is useful for calendar clients that do not support CalDAV well, especially Outlook and Google Calendar.

An ICS feed is a secret URL ending with .ics. Anyone with the URL can read that team's exported on-call calendar, so treat the URL like a password.

When to use ICS feeds#

Use ICS feeds for clients that support subscribing to an internet calendar URL.

Client	Recommended method
Outlook on the web	ICS subscription
New Outlook	ICS subscription
Google Calendar	ICS subscription
Apple Calendar	CalDAV preferred
Thunderbird	CalDAV or ICS

For Apple Calendar, Thunderbird and DAVx5, see CalDAV calendar sync.

Create an ICS feed#

Open Calendar.
Select a specific team. Export is not available for the "all teams" view.
Click Export.
Create a feed if one does not already exist.
Copy the generated feed URL.

The feed URL looks like this:

https://incidentrelay.example.com/api/calendar/feeds/<secret-token>.ics

The token is shown when the feed is created or regenerated. Existing feed list responses should not expose the token again.

In Outlook on the web or new Outlook:

Open Calendar.
Choose Add calendar.
Choose Subscribe from web.
Paste the IncidentRelay .ics URL.
Choose a name and color.
Save.

Outlook refresh frequency is controlled by Outlook and may not be immediate.

In Google Calendar:

Open Other calendars.
Click +.
Choose From URL.
Paste the IncidentRelay .ics URL.
Click Add calendar.

Google Calendar refresh frequency is controlled by Google and may take time.

CalDAV is recommended for Apple Calendar, but an ICS subscription can also be used.

On macOS:

Open Calendar.
Choose File → New Calendar Subscription.
Paste the IncidentRelay .ics URL.
Configure auto-refresh.

If you want automatic discovery of all accessible teams, use CalDAV instead.

Feed management#

Regenerate token#

Regenerating a feed token creates a new secret URL and immediately invalidates the old URL.

Use this when:

the URL was shared with the wrong person;
the URL may have leaked;
a user who had the URL should no longer be able to use it.

After regeneration, update calendar subscriptions with the new URL.

Delete feed#

Deleting a feed disables the subscription URL. Calendar clients using the old URL will stop refreshing successfully.

Inactive team or group#

If the team or its group becomes inactive, the feed returns 403 Forbidden.

API endpoints#

Management endpoints require normal IncidentRelay API authentication and permissions.

GET    /api/calendar/feeds?team_id=<team_id>
POST   /api/calendar/feeds
POST   /api/calendar/feeds/<feed_id>/token
DELETE /api/calendar/feeds/<feed_id>

The subscription endpoint is public but protected by the secret token in the URL:

GET /api/calendar/feeds/<secret-token>.ics

Only the .ics subscription endpoint should be public. Do not make all /api/calendar/feeds/ endpoints public.

Example API usage#

Create a feed:

curl -s \
  -X POST \
  -H 'Authorization: Bearer INCIDENTRELAY_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"team_id":1,"name":"Cloud OPS subscription","past_days":7,"future_days":90}' \
  https://incidentrelay.example.com/api/calendar/feeds

Download the feed:

curl -i https://incidentrelay.example.com/api/calendar/feeds/<secret-token>.ics

A successful response should have:

Content-Type: text/calendar
Cache-Control: no-store

Security notes#

The feed URL is a bearer secret.
Anyone with the .ics URL can read the exported team calendar.
Use HTTPS in production.
Regenerate the token if the URL leaks.
Delete the feed to disable the URL completely.
Do not log full feed tokens.
Do not expose tokenized URLs in public issue trackers, chat rooms or screenshots.

Troubleshooting#

Calendar client says the URL is invalid#

Check that the URL ends with .ics and is reachable from the client network.

https://incidentrelay.example.com/api/calendar/feeds/<secret-token>.ics

Feed returns 404#

The token is invalid, regenerated, deleted or copied incorrectly.

Create a new feed or regenerate the token.

Feed returns 403#

The feed exists, but the team or group is inactive.

Reactivate the team/group or create a feed for an active team.

Events do not update immediately#

Outlook and Google Calendar control their own refresh intervals. IncidentRelay returns the current ICS content, but the external service may cache the subscription.

Feed is empty#

The team may have no rotations or no generated on-call slots in the configured export range.

Check the feed settings:

past_days
future_days

Increase future_days if the exported range is too short.

ICS calendar feeds