Skip to main content

Webhooks

Appcircle will notify external services via webhooks when a certain event occurs. When the events you specified happen, we'll send a POST request in JSON format to the URLs you provide.

Creating Webhook​

Multiple webhooks can be created for different events and build profiles. To start, go to My Organization Integration screen and press the Manage button next to Webhook under the Connections section.

  • Click Add Webhook button to create your webhook
  • Fill in the details of your webhook

Webhook Scope:

Type of events that you want to be notified. The following scopes are supported

  • Build
  • Signing Identity
  • Distribution
  • Store Submit
  • Enterprise Store

Each scope has different events. You can select the events you want to get notified about. For example for the Build scope, you may get the following events

  • Build Started
  • Build Successful
  • Build Failed
  • Build Canceled
  • Build Timeout
  • Fetch Started

Profile:

Some scopes support getting events for the selected build profile. You can choose the build profile from the list to get notified for that specific build profile.

Payload URL:

Appcircle will post events to this URL. It is highly recommended to choose the HTTPS URL.

Secret:

To verify that a Webhook post is coming from Appcircle, you may use this secret to verify the message body. HMAC-SHA256 of payload with your secret key should be the same as the hexadecimal signature you get in the ac_signature header

For example, if you used test as your secret and Appcircle sends you a webhook with following body,

{"deliveryId":"ee81f55b-fd14-4f95-9e1f-f5bce3ad29e4","timestamp":"2022-10-26T14:55:08.4622757+00:00","action":"Build|BuildStart","message":"Build started for the develop branch for the profile pr_mr_tag_test https://my.appcircle.io/build/detail/7f17fdb4-46e7-40c3-a01d-1ef18de06890","title":"Build Started","item":{"id":"9e3c7dcd-d292-4144-9844-ca07df6a8924","agentId":"4026b6f2-d298-4b54-aa31-64726ad076fc","organizationId":"6fbd094c-18cb-4bcd-bc6f-cf2aee752982","userId":"6320a79e-d1f0-45d0-a38e-920dc4c30644","profileId":"7f17fdb4-46e7-40c3-a01d-1ef18de06890","branchId":"3779c7d2-c826-4596-95f2-52486bf75471","buildId":"00000000-0000-0000-0000-000000000000","commitId":"ba50d2d6-bfcc-49a1-8fa6-6e00711b4d5b","taskId":"9e3c7dcd-d292-4144-9844-ca07df6a8924","purpose":1,"triggerReason":0,"cancelling":false,"queueItemStatus":1,"xcodeVersion":""},"links":{"detail":"https://my.appcircle.io/build/detail/7f17fdb4-46e7-40c3-a01d-1ef18de06890","viewlogs":"https://my.appcircle.io/build/detail/7f17fdb4-46e7-40c3-a01d-1ef18de06890?modal=/build/modal/Logs&profileId=7f17fdb4-46e7-40c3-a01d-1ef18de06890&commitId=ba50d2d6-bfcc-49a1-8fa6-6e00711b4d5b&buildId=9e3c7dcd-d292-4144-9844-ca07df6a8924&scope=build&method=get"}}

Calculating HMAC-256 of this payload with test should give you

8470172a1c60447abd7dce97227448da2b369b17d54d128306625979eca6476b This value must be the same as the value of ac_signature header of the request.

You may also check the timestamp of the payload to prevent replay attacks. You may give 5-10 minutes of a threshold for the timestamp for late webhook deliveries.

Request History​

You can check all the webhooks Appcircle sends to your endpoint by clicking the... button and then clicking the Request History section.

You can see all the requests and their results by clicking on them.

Editing Webhook​

You can edit your webhook by clicking the... button and then clicking the Edit section.

Deleting Webhook​

You can edit your webhook by clicking the... button and then clicking the Delete section.

tip

You may use https://webhook.site to test and inspect your webhooks.