What are webhooks?

Webhooks are a simple way for two applications to communicate with one another via standard web HTTP protocols. When an event occurs in app A, a standard message will be sent to a URL managed by app B. As opposed to app B using app A's API to periodically “pull” batch information about events that occur in app A, with webhooks app A will “push” each individual event in real-time to app B as soon as they occur. 

In the context of this feature, you can “subscribe” to one or more core Appcues events and send information about that event to a different tool of your choice as soon as it occurs. The tool could be a different third-party service, your own web application, or your own database for example.

Use cases

Webhooks allow for simple integrations to be built between any app that can send webhook messages and any app that can receive them. Webhooks are a common pattern in web apps today, so there are many possibilities! Here are a few:

• Ops team monitoring: Whenever a user completes an onboarding Checklist, add a row to a Google sheet that my ops team monitors. 
   
• CRM activity feeds: When a user answers an Appcues NPS survey, send their score and comment to their activity feed in your CRM, in order to automate follow-up outreach. 
   
• Feed events into your analytics tools: Add Flow started and completed events to your third-party analytics platform, internal databases, or dashboarding tools, to do more funnel analysis on the types of events users are performing in your product after they complete Appcues Flows.
   
• Email follow-up: Trigger a follow-up email when a user skips a welcome Flow, to provide them the same content in an email for the user to read later.
   
• Team chat alerting: When a user completes a feedback Flow for a new feature send feedback text to your product team’s Microsoft Teams channel. 

Event subscriptions supported

Appcues webhooks can be set up to trigger off of the following events:

• NPS Score
• NPS Feedback
• Web Flow Completed
• Web Flow Started
• Web Flow Button Clicked
• Web Flow Form Submitted
• Web Flow Skipped
• Checklist Item Completed
• Checklist Completed
• Checklist Skipped
• Checklist Shown
• Mobile Flow Started
• Pin Interacted

Creating a webhook

Go to the Integrations page and click the Webhooks card to go to the management page:

(Note: Webhooks can only be created and edited by users with Admin permissions).

Webhooks only need a few pieces of information to enable and begin sending event information, You can set up a webhook to fire anytime certain events occur:

Or you can further filter the webhook to only fire when certain events occur on certain Flows and other experiments:

Webhook security

When a webhook configuration in Appcues includes an account secret key, the event message will include two security HTTP headers: X-Apc-Signature and X-Apc-Timestamp. For example:

X-Apc Signature : You can use this value to verify that the message was sent to you by Appcues and not a third party. Here is how this value is generated:

1.  A string is created by combining the system timestamp at the time of the operation and the webhook's message body: timestamp:body
2.  The string above is hashed using the account secret key and SHA256 encryption.

X-Apc-Timestamp : You can use this value to check for a replay attack, since the correct timestamp is part of the X-Apc-Signature generation.

Payload examples

NPS Score

{
  "account_id": "94742",
  "attributes": {
   	"_prev_nps_score": null,
  	"_prev_nps_score_time": null,
  	"flowId": "c32fb928-7a1a-4feb-8993-696aa68fe5fb",
  	"flowName": "NPS Survey",
  	"flowType": "satisfaction-survey",
  	"flowVersion": 1664820161117,
  	"localeId": "default",
  	"localeName": "default",
  	"score": 10,
  	"sessionId": 1670422599749
  },
  "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
  "group_id": null,
  "id": "7ed17098-dcb0-4602-a9d7-8e7605577f19",
  "ingested_at": 1684439316408,
  "name": "appcues:nps_score",
  "source": null,
  "timestamp": 1684439316293,
  "user_id": "anon:a24a871a-74f2-450e-b079-95672ac6ba52"
}

NPS Feedback

{
  "account_id": "94742",
  "attributes": {
   	"feedback": "great stuff",
  	"flowId": "c32fb928-7a1a-4feb-8993-696aa68fe5fb",
  	"flowName": "NPS Survey",
  	"flowType": "satisfaction-survey",
  	"flowVersion": 1664820161117,
  	"localeId": "default",
  	"localeName": "default",
  	"sessionId": 1670422599749
  },
  "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
  "group_id": null,
  "id": "7ed17098-dcb0-4602-a9d7-8e7605577f19",
  "ingested_at": 1684439316408,
  "name": "appcues:nps_score",
  "source": null,
  "timestamp": 1684439316293,
  "user_id": "anon:a24a871a-74f2-450e-b079-95672ac6ba52"
}

Web Flow Completed

{
  "account_id": "94742",
  "attributes": {
    "flowId": "daf26add-b4ec-466e-92a7-349defcd55fa",
    "flowName": "Modal Test",
    "flowType": "journey",
    "flowVersion": 1684507357284,
    "sessionId": 1684868248856
  },
  "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
  "group_id": null,
  "id": "7e691fdc-842a-4b39-9288-3bfa76084b75",
  "ingested_at": 1684868251991,
  "name": "appcues:flow_completed",
  "timestamp": 1684868251905,
  "user_id": "anon:1c499266-100c-477a-93cb-025fe02a9589"
}

Web Flow Started

{
  "account_id": "94742",
  "attributes": {
    "flowId": "daf26add-b4ec-466e-92a7-349defcd55fa",
    "flowName": "Modal Test",
    "flowType": "journey",
    "flowVersion": 1684507357284,
    "sessionId": 1684867470575
  },
  "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
  "group_id": null,
  "id": "0deb801e-d48b-4610-9c8a-bf333b9a5cda",
  "ingested_at": 1684867471407,
  "name": "appcues:flow_started",
  "timestamp": 1684867471283,
  "user_id": "anon:7def0d8b-00e9-4a96-9399-67ce2b1252fd"
}

Web Flow Button Clicked

{
  "account_id": "94742",
  "attributes": {
    "flowId": "daf26add-b4ec-466e-92a7-349defcd55fa",
    "flowName": "Modal Test",
    "flowType": "journey",
    "flowVersion": 1684507357284,
    "interaction": {
      "category": "internal",
      "destination": "end-flow",
      "text": "Next"
    },
    "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
    "interactionType": "click",
    "sessionId": 1684868063974,
    "stepChildId": "fe3e9b79-2e90-488b-a698-7440229820c9",
    "stepChildNumber": 0,
    "stepId": "69bf781b-a660-43ea-8f2f-7580dfc4eee3",
    "stepNumber": 0,
    "stepType": "modal"
  },
  "group_id": null,
  "id": "0125feb0-2f14-4f83-a820-b971243c3ebf",
  "ingested_at": 1684868069159,
  "name": "appcues:step_interacted",
  "timestamp": 1684868069070,
  "user_id": "anon:1c499266-100c-477a-93cb-025fe02a9589"
}

Web Flow Form Submitted

{
  "account_id": "94742",
  "attributes": {
    "flowId": "daf26add-b4ec-466e-92a7-349defcd55fa",
    "flowName": "Modal Test",
    "flowType": "journey",
    "flowVersion": 1684507357284,
    "interaction": {
      "category": "form",
      "formId": null,
      "response": [
        {
          "fieldId": "83038f4a-2505-47fb-9092-ec72ca3eb981",
          "fieldRequired": false,
          "fieldType": "null",
          "label": "What's your role at the company?",
          "value": "Product Manager"
        }
      ]
    },
    "interactionType": "submit",
    "sessionId": 1684868063974,
    "stepChildId": "fe3e9b79-2e90-488b-a698-7440229820c9",
    "stepChildNumber": 0,
    "stepId": "69bf781b-a660-43ea-8f2f-7580dfc4eee3",
    "stepNumber": 0,
    "stepType": "modal"
  },
  "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
  "group_id": null,
  "id": "0129c911-380b-4554-ab84-0e1cab7919eb",
  "ingested_at": 1684868069159,
  "name": "appcues:form_submitted",
  "timestamp": 1684868069056,
  "user_id": "anon:1c499266-100c-477a-93cb-025fe02a9589"
}

Web Flow Skipped

{
  "account_id": "94742",
  "attributes": {
    "flowId": "daf26add-b4ec-466e-92a7-349defcd55fa",
    "flowName": "Modal Test",
    "flowType": "journey",
    "flowVersion": 1684507357284,
    "sessionId": 1684868368272,
    "stepId": "69bf781b-a660-43ea-8f2f-7580dfc4eee3",
    "stepNumber": 0
  },
  "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
  "group_id": null,
  "id": "e313efaa-a621-4db4-be99-012928c47722",
  "ingested_at": 1684868370405,
  "name": "appcues:flow_skipped",
  "timestamp": 1684868370285,
  "user_id": "anon:1c499266-100c-477a-93cb-025fe02a9589"
}

Checklist Item Completed

{
  "account_id": "94742",
  "attributes": {
    "checklistId": "cb4f19a2-43a7-42ea-a860-16c9be3cfe43",
    "checklistName": "Journeys checklist",
    "itemId": "05be3915-7e70-4b2d-ae4b-f3f56b91e061",
    "itemIndex": 0,
    "itemLabel": "Complete tutorial",
    "sessionId": 1684868642856
  },
  "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
  "group_id": null,
  "id": "76ccf047-c216-4324-add5-32bf6b780172",
  "ingested_at": 1684868643253,
  "name": "appcues:checklist_item_completed",
  "timestamp": 1684868643142,
  "user_id": "anon:1c499266-100c-477a-93cb-025fe02a9589"
}

Checklist Completed

{
  "account_id": "94742",
  "attributes": {
    "checklistId": "cb4f19a2-43a7-42ea-a860-16c9be3cfe43",
    "checklistName": "Journeys checklist",
    "sessionId": 1684868642856
  },
  "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
  "group_id": null,
  "id": "21430f65-65ac-48a2-a671-1c9e0ff31c8b",
  "ingested_at": 1684868643252,
  "name": "appcues:checklist_completed",
  "timestamp": 1684868643141,
  "user_id": "anon:1c499266-100c-477a-93cb-025fe02a9589"
}

Checklist Skipped

{
  "account_id": "94742",
  "attributes": {
    "checklistId": "cb4f19a2-43a7-42ea-a860-16c9be3cfe43",
    "checklistName": "Journeys checklist",
    "sessionId": 1684441654617
  },
  "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
  "group_id": null,
  "id": "6ece7bef-64ac-489d-8ac4-03323af01110",
  "ingested_at": 1684441658142,
  "name": "appcues:checklist_skipped",
  "source": null,
  "timestamp": 1684441658013,
  "user_id": "anon:061e8c23-a2db-4dad-b538-6dd9932461f8"
}

Checklist Shown

{
  "account_id": "94742",
  "attributes": {
    "checklistId": "cb4f19a2-43a7-42ea-a860-16c9be3cfe43",
    "checklistName": "Journeys checklist",
    "sessionId": 1684868642856
  },
  "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
  "group_id": null,
  "id": "baef6f24-5e56-4ea6-b064-b65cbb5b00c4",
  "ingested_at": 1684868644394,
  "name": "appcues:checklist_shown",
  "timestamp": 1684868644274,
  "user_id": "anon:1c499266-100c-477a-93cb-025fe02a9589"
}

Mobile Flow Started

{
  "account_id": "94742",
  "attributes": {
    "experienceId": "5e9e9ab6-4dca-4596-b52d-d59052f96892",
    "experienceName": "Mobile Control",
    "experienceType": "mobile",
    "interactionType": "Button Tapped",
    "stepId": "25e1c534-8c6b-47fc-a343-6fb22d179d74",
    "stepType": "modal",
    "version": 1684442952071
  },
  "group_id": null,
  "id": "bf1baa7e-0c61-4d9d-a437-37bef45566b0",
  "ingested_at": 1684869295614,
  "name": "appcues:v2:step_interaction",
  "timestamp": 1684869287097,
  "user_id": "g1j77no"
}

Pin Interacted

{
  "account_id": "94742",
  "attributes": {
    "experienceId": "df38c205-aef4-45e0-91e6-e848b117899c",
    "experienceName": "Pin A Condition",
    "experienceType": "persistent",
    "interactionType": "Button Pin Clicked",
    "stepId": "3b188f86-d230-4fbb-8e9f-1133b09f8023",
    "stepName": "Pin 1",
    "stepType": "button"
  },
  "context": {
    "url": "https://appcues.github.io/flow-testbench/"
  },
  "group_id": null,
  "id": "b0f11cb2-f3d7-4b5b-b70e-80a46ad58a2a",
  "ingested_at": 1684869173769,
  "name": "appcues:v2:step_interaction",
  "timestamp": 1684869172760,
  "user_id": "anon:1c499266-100c-477a-93cb-025fe02a9589"
}