Slack Events: Handling the URL Verification Event

Overview

This process had quite a few gotchas that I missed during implementation for Slack's URL Verification process for setting up an events webhook.

I work for Akkio, where I'm building out a no-code predictive AI platform. If you're looking to harness the power of AI without needing a data scientist, give us a try!

What does the endpoint expect?

The request expects a few things.

• The endpoint returns the provided challenge value either as plaintext or as a { "challenge": "..." } JSON value. Make sure you set the Content-Type header accordingly.
• Return a 200, not a 201 or something similar.
• The request is a POST, not a GET.

The main thing I misunderstood was that the url_verification event is not wrapped in an outer event like the rest of them. It's just three attributes in a single JSON object, nothing nested.

Final Implementation

I'm using FastAPI, a prominent REST API framework for Python. You can likely extrapolate the general solution to whatever you're using.

Here's our actual code. Treat it all as pseudocode that may require minor changes, especially if you're translating across platforms.

The main controller:

from fastapi.responses import PlainTextResponse
router = fastapi.APIRouter(prefix="/events")
import slack_app.events.models as SlackEventModels

@router.post(
    "",
    description="Slack Webhook Handler. Used to do things like respond to users that mention the ap.",
    status_code=200,
    tags=["slack", "webhooks"],
    response_class=PlainTextResponse
)
async def _handle_slack_events(request: fastapi.Request) -> Any:
    try:
        # Special case for one-time verification handleshake; Slack has you use the deprecated verification token for
        # this rather than the new signing method
        verification_body = SlackEventModels.VerificationHandshakeEvent(**await request.json())
        if verification_body.token != SETTINGS.SLACK_VERIFICATION_TOKEN:
            raise fastapi.HTTPException(status_code=401, detail="Invalid Slack Verification Token")
        return PlainTextResponse(verification_body.challenge, headers={"Content-Type": "text/plain"})
    except pydantic.ValidationError:
        # Just means it isn't a verification handshake; there are probably cleaner ways to handle, but this works fine
        pass

The referenced payload body definition we validate against:

class VerificationHandshakeEvent(pydantic_config.BaseConfig):
    type: Literal["url_verification"]
    token: str # Slack legacy verification token; we use modern version and ignore this
    challenge: str

There's a bit of syntactic sugar, especially with the inheritance from a Pydantic class, but it's ultimately just a type field that'll always be url_verification, a token field that will be the legacy validation token that you get when creating a Slack app, and a challenge value that you're expected to return as plaintext.

Conclusion

Hope you enjoyed! If I saved you some time and you'd like to support my work, check out my Sponsors page on GitHub.