Back to Integrations Guides

Setting Up an Outgoing Webhook

Introduction

Setting up a webhook takes a couple of minutes and doesn’t require any code. You’ll create an integration, save a secret, and choose which events you want to be notified about. Here’s the whole flow.

Create the integration

From your site’s dashboard in AAArdvark, here’s how to get started:

  1. Open the Integrations page for the site you want notifications for (Site Dashboard > Integrations).
  2. Click Add Integration and pick Outgoing Webhook.
  3. Enter the web address (URL) where you’d like deliveries to arrive.

Your address needs to be secure (HTTPS). We’ll only send to an endpoint with a valid, public TLS certificate. Self-signed or expired certificates get rejected, and after a few quick retries, the delivery is dropped. If you’re just testing on your own machine, a tunneling tool like ngrok gives you a valid certificate without any fuss. Reach for that rather than turning off TLS.

Save your secret

When you save the integration, AAArdvark shows you a secret string – and it’s shown only once, right there on the configuration screen. Copy it straight away and keep it somewhere your service can read it, like a WEBHOOK_SECRET environment variable.

Why does it matter? That secret is what lets your endpoint confirm a message genuinely came from AAArdvark and not from someone pretending to be us. Without it, there’s no way to tell the difference. (The signature verification guide walks through exactly how that check works.)

Lost it? You can regenerate a new secret from the same screen at any time. Just remember to update your endpoint with the new value – until you do, anything still using the old secret will stop verifying.

Choose which events to hear about

You decide which events trigger a webhook, so you only get the notifications you actually want. You can mix and match across these categories on a single integration:

Issue events

  • A new issue is logged (issue.created) – a fresh accessibility problem turns up on your site.
  • An issue changes status (issue.status_changed) – for example, it moves from Active to Resolved Pending.

Issue instance events

  • A new instance is logged (issue_instance.created) – one specific occurrence of a problem on one specific page.
  • An instance changes status (issue_instance.status_changed) – that one occurrence moves between states.

Scan events

  • A scan finishes (scan.completed) – a scan wraps up, with a summary of what it found.

Before you save, click Test Connection. We’ll send a sample event to your URL so you can confirm everything’s wired up and your endpoint replies with a success (status 200).

Sending to more than one place? If you set up two outgoing webhooks on the same site and both listen for the same event, each one gets its own copy – so the event reaches both endpoints. Every copy still carries its own unique delivery ID, so duplicate-handling keeps working independently for each endpoint.

What your endpoint needs to do

Your receiving endpoint has a short list of responsibilities:

  • Accept POST requests that arrive as JSON (Content-Type: application/json).
  • Reply with a success code (any 2xx) within a few seconds to let us know it arrived.
  • Only reply with an error – or stay silent – when you actually want us to try again.
  • If it has real work to do, acknowledge first and do that work in the background, so the request doesn’t time out.

Still stuck?

File a support ticket with our five-star support team to get more help.

File a ticket

  • This field is for validation purposes and should be left unchanged.
  • Please provide any information that will be helpful in helping you get your issue fixed. What have you tried already? What results did you expect? What did you get instead?

Related Guides